harn_cli/cli/
mod.rs

1//! Top-level clap definition for the `harn` CLI.
2//!
3//! Per-subcommand arg structs live in their own modules under
4//! `crates/harn-cli/src/cli/`. The `Cli` and `Command` enum here only
5//! reference types via `pub(crate) use ...` re-exports so external
6//! consumers can keep using `crate::cli::TypeName` unchanged.
7//!
8//! Some variants of subcommand enums are reached only by destructuring
9//! the parent (`SubCommand::Foo(args) => ...`) and are never referenced
10//! by name from outside this module. Those types stay private to their
11//! per-subcommand module and are accessed through their parent enum.
12
13mod app;
14mod bench;
15mod canon;
16mod check;
17mod codemod;
18mod completion;
19mod config_cmd;
20mod conformance_helper;
21mod connect;
22mod connector;
23mod contracts;
24mod crystallize;
25mod dap;
26mod demo;
27mod dev;
28mod doc;
29mod doctor;
30mod dump;
31mod eval;
32mod explain;
33mod fix;
34mod flow;
35mod graph;
36mod guard;
37mod host;
38mod init;
39mod lint_fmt;
40mod local;
41mod mcp;
42mod merge_captain;
43mod models;
44mod orchestrator;
45mod pack;
46mod package;
47mod parse_tokens;
48mod persona;
49mod pg;
50mod playground;
51mod portable;
52mod portal;
53mod precompile;
54mod profile;
55mod provider;
56mod providers;
57mod quickstart;
58mod routes;
59mod rule;
60mod run;
61pub(crate) mod run_source;
62pub(crate) mod runs;
63mod sandbox;
64mod scan;
65mod serve;
66mod session;
67mod skill;
68mod skills;
69mod supervisor;
70mod test;
71mod test_bench;
72mod time;
73mod tool;
74mod trace;
75mod trigger;
76mod trust;
77mod try_cmd;
78mod upgrade;
79mod usage;
80mod util;
81mod verify;
82mod version;
83mod viz;
84mod watch;
85mod workflow;
86
87pub(crate) use app::{AppArgs, AppCommand};
88pub(crate) use bench::{BenchArgs, BenchCommand, BenchPortableArgs, BenchReplayArgs};
89pub(crate) use canon::{CanonArgs, CanonCheckArgs, CanonCommand};
90pub(crate) use check::{CheckArgs, CheckOutputFormat};
91pub(crate) use codemod::CodemodArgs;
92pub(crate) use completion::{CompletionArgs, CompletionShell};
93pub(crate) use config_cmd::{ConfigArgs, ConfigCommand, ConfigInspectArgs, ConfigValidateArgs};
94pub(crate) use conformance_helper::{
95    ConformanceHelperArgs, ConformanceHelperBridgeMockHostArgs, ConformanceHelperCommand,
96    ConformanceHelperHttpProxyArgs,
97};
98pub(crate) use connect::{
99    ConnectApiKeyArgs, ConnectArgs, ConnectCommand, ConnectGenericArgs, ConnectGithubArgs,
100    ConnectLinearArgs, ConnectOAuthArgs, ConnectSetupPlanArgs, ConnectStatusArgs,
101};
102pub(crate) use connector::{ConnectorArgs, ConnectorCheckArgs, ConnectorCommand};
103pub(crate) use contracts::{
104    ContractsArgs, ContractsBundleArgs, ContractsCommand, ContractsHostCapabilitiesArgs,
105    ContractsOutputArgs,
106};
107pub(crate) use crystallize::{
108    CrystallizeArgs, CrystallizeCommand, CrystallizeIngestArgs, CrystallizeShadowArgs,
109    CrystallizeValidateArgs,
110};
111pub(crate) use dap::DapArgs;
112pub(crate) use demo::DemoArgs;
113pub(crate) use dev::DevArgs;
114pub(crate) use doc::DocArgs;
115pub(crate) use doctor::DoctorArgs;
116pub(crate) use dump::{
117    ConnectorSchemaCodegenArgs, DumpConnectorMatrixArgs, DumpHarnessMigrationsArgs,
118    DumpHighlightKeywordsArgs, DumpPortableBenchmarkSchemaArgs, DumpPromptGrammarArgs,
119    DumpProtocolArtifactsArgs, DumpTriggerQuickrefArgs,
120};
121pub use eval::{
122    EvalArgs, EvalCodingAgentArgs, EvalCommand, EvalContextArgs, EvalPromptArgs, EvalPromptMode,
123    EvalPromptOutput, EvalScopeTriageArgs, EvalSkillGateArgs, EvalToolCallsArgs,
124    EvalToolCallsCommand, EvalToolCallsRegressionArgs,
125};
126pub(crate) use explain::{CatalogFormat, ExplainArgs};
127pub(crate) use fix::FixArgs;
128pub(crate) use flow::{
129    FlowArchivistCommand, FlowArchivistScanArgs, FlowArgs, FlowCommand, FlowReplayAuditArgs,
130    FlowShipCommand, FlowShipWatchArgs,
131};
132pub(crate) use graph::GraphArgs;
133pub(crate) use guard::{
134    GuardArgs, GuardCommand, GuardInstallArgs, GuardListArgs, GuardRemoveArgs, GuardStatusArgs,
135};
136pub(crate) use host::{
137    HostArgs, HostCommand, HostLeaseAcquireArgs, HostLeaseArgs, HostLeaseCommand,
138    HostLeasePriorityArg, HostLeaseReleaseArgs, HostLeaseRenewArgs, HostLeaseResourceClassArg,
139    HostLeaseRunArgs, HostLeaseRunCargoArgs, HostLeaseRunCargoWorkerArgs, HostLeaseRunCommand,
140    HostLeaseStatusArgs,
141};
142pub(crate) use init::{InitArgs, NewArgs, ProjectTemplate};
143pub(crate) use lint_fmt::{FmtArgs, PathTargetsArgs};
144pub(crate) use local::{
145    LocalArgs, LocalCommand, LocalLaunchArgs, LocalListArgs, LocalProfileArgs, LocalStatusArgs,
146    LocalStopArgs, LocalSwitchArgs,
147};
148pub(crate) use mcp::{
149    McpArgs, McpCallArgs, McpCommand, McpDiscoverArgs, McpLoginArgs, McpMockCommand,
150    McpMockEvalArgs, McpMockRecordArgs, McpMockReplayArgs, McpMockVerifyArgs, McpMockWorldArgs,
151    McpPresetsArgs, McpServeArgs, McpServerRefArgs,
152};
153pub(crate) use merge_captain::{
154    MergeCaptainArgs, MergeCaptainAuditArgs, MergeCaptainAuditFormat, MergeCaptainBackendKind,
155    MergeCaptainCommand, MergeCaptainIterateArgs, MergeCaptainIterateFormat,
156    MergeCaptainLadderArgs, MergeCaptainLadderFormat, MergeCaptainMockCleanupArgs,
157    MergeCaptainMockCommand, MergeCaptainMockInitArgs, MergeCaptainMockServeArgs,
158    MergeCaptainMockStatusArgs, MergeCaptainMockStepArgs, MergeCaptainRunArgs,
159};
160pub(crate) use models::{
161    ModelInfoArgs, ModelRecommendArgs, ModelsArgs, ModelsBatchArgs, ModelsBatchCancelArgs,
162    ModelsBatchCommand, ModelsBatchDownloadArgs, ModelsBatchExecuteArgs, ModelsBatchExecuteCommand,
163    ModelsBatchExecuteInitArgs, ModelsBatchManifestArgs, ModelsBatchPlanArgs,
164    ModelsBatchPrepareArgs, ModelsBatchRejoinArgs, ModelsBatchStatusArgs, ModelsBatchSubmitArgs,
165    ModelsCommand, ModelsInstallArgs, ModelsListArgs, ModelsListSort, ModelsLoraArgs,
166    ModelsLoraBehaviorStrataPolicy, ModelsLoraCommand, ModelsLoraExportArgs, ModelsLoraInspectArgs,
167    ModelsLoraManifestArgs, ModelsLoraPlanArgs, ModelsLoraPreflightArgs, ModelsLoraPromoteArgs,
168    ModelsLoraTrainArgs, ModelsTestArgs,
169};
170pub(crate) use orchestrator::{
171    OrchestratorArgs, OrchestratorCommand, OrchestratorDeployArgs, OrchestratorDeployProvider,
172    OrchestratorDlqArgs, OrchestratorFireArgs, OrchestratorInspectArgs, OrchestratorLocalArgs,
173    OrchestratorLogFormat, OrchestratorQueueArgs, OrchestratorQueueCommand,
174    OrchestratorQueueDrainArgs, OrchestratorQueueLsArgs, OrchestratorQueuePurgeArgs,
175    OrchestratorRecoverArgs, OrchestratorReloadArgs, OrchestratorReplayArgs,
176    OrchestratorReplayOracleArgs, OrchestratorResumeArgs, OrchestratorServeArgs,
177    OrchestratorStatsArgs, OrchestratorTenantArgs, OrchestratorTenantCommand,
178    OrchestratorTenantCreateArgs, OrchestratorTenantDeleteArgs, OrchestratorTenantLsArgs,
179    OrchestratorTenantSuspendArgs,
180};
181pub use pack::{PackArgs, PackCommand, PackRepackArgs, PackUnpackArgs, PackVerifyArgs};
182pub(crate) use package::{
183    AddArgs, InstallArgs, PackageArgs, PackageArtifactsCommand, PackageCacheCommand,
184    PackageCommand, PackageRegistryCommand, PackageScaffoldCommand, PackageScaffoldOpenapiArgs,
185    PackageSearchArgs, PackageVerifyArgs, PublishArgs, RemoveArgs, UpdateArgs,
186};
187pub(crate) use parse_tokens::{ParseArgs, TokensArgs};
188pub(crate) use persona::{
189    PersonaActivateArgs, PersonaActivationsArgs, PersonaArgs, PersonaCheckArgs, PersonaCommand,
190    PersonaCompilePromptArgs, PersonaControlArgs, PersonaDeactivateArgs, PersonaDoctorArgs,
191    PersonaInspectArgs, PersonaListArgs, PersonaMaterializeArgs, PersonaNewArgs, PersonaSpendArgs,
192    PersonaStatusArgs, PersonaSupervisionCommand, PersonaSupervisionTailArgs, PersonaTemplateKind,
193    PersonaTickArgs, PersonaTriggerArgs,
194};
195pub(crate) use pg::{PgArgs, PgCodegenArgs, PgCommand};
196pub(crate) use playground::PlaygroundArgs;
197pub(crate) use portable::{
198    PortableArgs, PortableCommand, PortableCompileArgs, PortableEntryKindArg, PortablePackageArgs,
199    PortableResumeArgs, PortableStartArgs,
200};
201pub(crate) use portal::PortalArgs;
202pub use precompile::PrecompileArgs;
203pub(crate) use profile::ProfileArgs;
204pub(crate) use provider::ProviderToolProbeFormatArg;
205#[cfg(test)]
206pub(crate) use provider::ProviderToolProbeModeArg;
207pub(crate) use provider::{
208    refresh_provider_catalog_if_requested, ProviderArgs, ProviderCacheProbeArgs,
209    ProviderCapabilitiesArgs, ProviderCapabilitiesCommand, ProviderCapabilitiesPromoteFromEvalArgs,
210    ProviderCommand, ProviderDispatchAuditArgs, ProviderDispatchAuditVariantArg,
211    ProviderDispatchExplainArgs, ProviderLimitsArgs, ProviderProbeArgs, ProviderToolCalibrateArgs,
212    ProviderToolProbeArgs, ProviderToolProbeAuditArgs, ProviderToolProbeCaseArg,
213    ProviderToolScorecardArgs,
214};
215pub(crate) use providers::{
216    ProviderCatalogCommand, ProvidersExportArgs, ProvidersGenerateArgs, ProvidersMatrixArgs,
217    ProvidersOverlayAuditArgs, ProvidersRecommendArgs, ProvidersRefreshArgs, ProvidersSupportArgs,
218    ProvidersValidateArgs,
219};
220pub(crate) use quickstart::QuickstartArgs;
221pub(crate) use routes::RoutesArgs;
222pub(crate) use rule::{RuleArgs, RuleCommand, RuleTestArgs};
223pub(crate) use run::RunArgs;
224pub(crate) use run_source::resolve_run_path_or_exit;
225pub(crate) use runs::{
226    run_runs_command, ReplayArgs, RunsArgs, RunsExportTrainingArgs, RunsReportArgs, RunsReviewArgs,
227};
228pub(crate) use sandbox::SandboxArgs;
229pub(crate) use scan::ScanArgs;
230pub(crate) use serve::{
231    A2aServeArgs, AcpServeTransport, ApiServeArgs, McpServeTransport, ServeAcpArgs, ServeArgs,
232    ServeCommand, ServeMcpArgs, ServeObsMode, ServeTlsMode, SiteServeArgs, WorkerServeArgs,
233};
234pub(crate) use session::{
235    SessionArgs, SessionCheckpointArgs, SessionCommand, SessionExportArgs, SessionImportArgs,
236    SessionListArgs, SessionSchemaArgs, SessionValidateArgs,
237};
238pub(crate) use skill::{
239    SkillArgs, SkillCommand, SkillEndorseArgs, SkillKeyCommand, SkillKeyGenerateArgs,
240    SkillSignArgs, SkillTrustAddArgs, SkillTrustCommand, SkillTrustListArgs, SkillVerifyArgs,
241    SkillWhoSignedArgs,
242};
243pub(crate) use skills::{
244    SkillsDumpArgs, SkillsGetArgs, SkillsInspectArgs, SkillsInstallArgs, SkillsListArgs,
245    SkillsMatchArgs, SkillsNewArgs, SkillsResolvedArgs, SkillsValidateArgs,
246};
247pub(crate) use supervisor::{
248    SupervisorArgs, SupervisorCommand, SupervisorDlqCommand, SupervisorDlqListArgs,
249    SupervisorDlqReplayArgs, SupervisorFireArgs, SupervisorInspectArgs, SupervisorListArgs,
250    SupervisorPauseArgs, SupervisorRecoverArgs, SupervisorReplayArgs, SupervisorResumeArgs,
251    SupervisorStartArgs, SupervisorStopArgs,
252};
253pub(crate) use test::{InternalConformanceWorkerMode, TestArgs};
254pub(crate) use test_bench::{
255    TestBenchArgs, TestBenchCommand, TestBenchExportAnnotationsArgs, TestBenchFidelityArgs,
256    TestBenchReplayArgs, TestBenchRunArgs, TestBenchValidateAnnotationsArgs,
257};
258pub(crate) use time::{TimeArgs, TimeCommand, TimeRunArgs};
259pub(crate) use tool::{ToolArgs, ToolCommand, ToolNewArgs};
260pub(crate) use trace::{TraceArgs, TraceCommand, TraceImportArgs};
261pub(crate) use trigger::{TriggerArgs, TriggerCancelArgs, TriggerCommand, TriggerReplayArgs};
262pub(crate) use try_cmd::TryArgs;
263pub(crate) use upgrade::UpgradeArgs;
264pub(crate) use usage::{UsageArgs, UsageGroupBy};
265// `TrustOutcomeArg` / `TrustTierArg` are referenced from the cli
266// parser tests only; they're matched via destructuring elsewhere.
267#[allow(unused_imports)]
268pub(crate) use trust::{
269    TrustArgs, TrustCommand, TrustExportArgs, TrustOutcomeArg, TrustQueryArgs, TrustTierArg,
270    TrustVerifyChainArgs,
271};
272pub(crate) use verify::VerifyArgs;
273pub(crate) use version::VersionArgs;
274pub(crate) use viz::VizArgs;
275pub(crate) use watch::WatchArgs;
276pub(crate) use workflow::{
277    WorkflowArgs, WorkflowCommand, WorkflowFunctionToolsArgs, WorkflowNestedCeilingArgs,
278    WorkflowPatchApplyArgs, WorkflowPatchCommand, WorkflowPatchPreviewArgs,
279    WorkflowPatchValidateArgs,
280};
281
282use clap::{Parser, Subcommand};
283
284#[derive(Debug, Parser)]
285#[command(
286    name = "harn",
287    about = "The agent harness language",
288    version,
289    disable_help_subcommand = false,
290    arg_required_else_help = true
291)]
292pub(crate) struct Cli {
293    /// Emit the JSON-schema catalog for every `harn` subcommand that
294    /// exposes a structured `--json` envelope. Pair with
295    /// `--command <name>` to print just one entry.
296    #[arg(long = "json-schemas", global = false)]
297    pub json_schemas: bool,
298
299    /// When combined with `--json-schemas`, restrict the catalog to a
300    /// single command name (e.g. `--command run`).
301    #[arg(
302        long = "command",
303        requires = "json_schemas",
304        value_name = "COMMAND",
305        global = false
306    )]
307    pub schema_command: Option<String>,
308
309    #[command(subcommand)]
310    pub command: Option<Command>,
311}
312
313#[derive(Debug, Subcommand)]
314pub(crate) enum Command {
315    /// Build and run interactive AI applications written in Harn.
316    App(AppArgs),
317    /// Compile and host deterministic portable Harn programs.
318    Portable(PortableArgs),
319    /// Execute a .harn file or an inline expression.
320    #[command(long_about = "\
321Execute a .harn file or an inline expression.
322
323USAGE
324    harn run script.harn
325    harn run -e 'log(\"hello\")'
326    harn run script.harn -- arg1 arg2   (script reads `argv` as list<string>)
327
328CONCURRENCY
329    Harn supports first-class concurrency primitives:
330      - spawn { ... }         — launch a task, return a handle
331      - parallel each LIST    — concurrent map
332      - parallel settle LIST  — concurrent map, collect Ok/Err
333      - parallel N            — N-way fan-out
334      - with { max_concurrent: N }  — cap in-flight workers
335      - channels, retry, select
336    https://harnlang.com/concurrency.html
337
338LLM THROTTLING
339    Providers can be rate-limited via `rpm:` in harn.toml / providers.toml
340    or via `HARN_RATE_LIMIT_<PROVIDER>=N`. Rate limits control throughput
341    (RPM); `max_concurrent` on `parallel` caps simultaneous in-flight jobs.
342
343SCRIPTING
344    LLM-readable one-pager: https://harnlang.com/docs/llm/harn-quickref.html
345    Human cheatsheet:       https://harnlang.com/scripting-cheatsheet.html
346    Full docs:              https://harnlang.com/
347")]
348    Run(RunArgs),
349    /// Type-check .harn files or directories without executing them.
350    Check(CheckArgs),
351    /// Parse a .harn file and print its AST.
352    Parse(ParseArgs),
353    /// Tokenize a .harn file and print lexer tokens.
354    Tokens(TokensArgs),
355    /// Inspect, validate, and emit schemas for layered Harn runtime config.
356    Config(ConfigArgs),
357    /// Explain a diagnostic. Pass a stable `HARN-<CAT>-<NNN>` code
358    /// (optionally with `--json` for the structured envelope), or the
359    /// legacy `--invariant <NAME> <FUNCTION> <FILE>` form to walk the
360    /// control-flow path behind a Harn invariant violation.
361    Explain(ExplainArgs),
362    /// Plan or apply repair-bearing diagnostics under an explicit safety ceiling.
363    Fix(FixArgs),
364    /// Export machine-readable Harn contracts and bundle manifests.
365    Contracts(ContractsArgs),
366    /// Lint .harn files or directories for common issues.
367    Lint(PathTargetsArgs),
368    /// Format .harn files or directories.
369    Fmt(FmtArgs),
370    /// Manage downloadable on-device injection-detection models (Layer 2).
371    Guard(GuardArgs),
372    /// Run user tests or the conformance suite.
373    Test(TestArgs),
374    /// Run a .harn script under a hermetic testbench (paused clock,
375    /// optional LLM/process tapes, fs overlay, deny-by-default network).
376    #[command(name = "test-bench")]
377    TestBench(TestBenchArgs),
378    /// Instrument a wrapped subcommand with phase-level wall-clock
379    /// timing (parse, typecheck, bytecode compile + cache hit/miss,
380    /// run setup, run main) plus per-LLM-call and per-tool-call
381    /// latency. Pair with `--json` for an agent-readable envelope.
382    Time(TimeArgs),
383    /// Scaffold a new project with harn.toml.
384    Init(InitArgs),
385    /// Scaffold a new project, package, or connector from a starter template.
386    New(NewArgs),
387    /// Diagnose the local Harn environment: toolchain version, configured
388    /// LLM providers and credentials, MCP server reachability, file
389    /// permissions on `~/.harn`, and project manifest health. Reports
390    /// each check as ok/warn/fail with a suggested fix.
391    Doctor(DoctorArgs),
392    /// Coordinate scarce machine resources through typed host leases.
393    Host(HostArgs),
394    /// Configure a starter Harn project and LLM provider settings.
395    Quickstart(QuickstartArgs),
396    /// Run a bundled offline demo scenario to see Harn in action without
397    /// API keys. `harn demo` lists scenarios; `harn demo <id>` runs one.
398    Demo(DemoArgs),
399    /// Register outbound connector resources with a provider.
400    Connect(Box<ConnectArgs>),
401    /// Validate pure-Harn connector packages against the connector contract.
402    Connector(ConnectorArgs),
403    /// Serve a Harn workflow over a transport adapter.
404    Serve(ServeArgs),
405    /// Manage remote MCP OAuth credentials and status.
406    Mcp(McpArgs),
407    /// Launch the Harn debug adapter (DAP) over stdio.
408    ///
409    /// Speaks the Debug Adapter Protocol on stdin/stdout so an editor — or a
410    /// scripted DAP client — can set breakpoints, step, and inspect variables
411    /// in a `.harn` program. This is the same server the `harn-dap` binary
412    /// alias runs; the subcommand makes it reachable with just `harn` on PATH.
413    Dap(DapArgs),
414    /// Watch a .harn file and re-run it on changes.
415    Watch(WatchArgs),
416    /// Watch a Harn project and re-typecheck only the modules whose
417    /// public interface fingerprint actually changed.
418    ///
419    /// USAGE
420    ///     harn dev --watch [<root>]
421    ///     harn dev --watch --json
422    ///     harn dev --watch --with-tests
423    ///
424    /// On each file change, the changed module's interface fingerprint
425    /// (BLAKE3 of types + signatures + `pub import` re-exports) is
426    /// recomputed. If it matches the previous fingerprint, only that
427    /// module is re-checked. If it changed, every transitive importer
428    /// is invalidated and re-checked. `--with-tests` extends the loop
429    /// to also re-run `test_*` / `@test`-attributed pipelines in
430    /// every invalidated module.
431    Dev(DevArgs),
432    /// Launch the local Harn observability portal.
433    Portal(PortalArgs),
434    /// Replay and inspect historical trigger dispatches from the event log.
435    Trigger(TriggerArgs),
436    /// Statically enumerate declared trigger routes and their requirements.
437    Routes(RoutesArgs),
438    /// Aggregate LLM spend/usage analytics from the local event log's
439    /// `provider_call_response` records: cost, tokens, and prompt-cache
440    /// efficiency rolled up by provider, model, or a day/week/month
441    /// time series. Reuses the runtime-computed `cost_usd` — no pricing
442    /// is recomputed. Pair with `--json` for an agent-readable envelope.
443    Usage(UsageArgs),
444    /// Statically enumerate modules, symbols, imports, capabilities, effects, and host calls.
445    Graph(GraphArgs),
446    /// Render Markdown API reference docs for a Harn file or project's `pub`
447    /// symbols (functions, consts, types, enums, structs), drawn from their
448    /// HarnDoc comments: signature, description, parameters, `@effects`,
449    /// `@errors`, and return type. Prints to stdout by default; pass
450    /// `--output <file>` to write a file (e.g. `docs/api.md`).
451    Doc(DocArgs),
452    /// Inspect Harn Flow atom, slice, and predicate audit state.
453    Flow(FlowArgs),
454    /// Evaluate harn-canon invariant packs against changed files.
455    Canon(CanonArgs),
456    /// Validate, preview, and run portable workflow bundles.
457    Workflow(WorkflowArgs),
458    /// Control local durable workflow automations for trusted hosts.
459    Supervisor(SupervisorArgs),
460    /// Import third-party eval traces into replayable Harn fixtures.
461    Trace(TraceArgs),
462    /// Mine repeated traces into a reviewable deterministic Harn workflow candidate.
463    Crystallize(CrystallizeArgs),
464    /// Query and manage trust-graph autonomy state.
465    Trust(TrustArgs),
466    /// Verify a signed Harn provenance receipt.
467    Verify(VerifyArgs),
468    /// Print shell completion script to stdout.
469    Completion(CompletionArgs),
470    /// Start the orchestrator process that hosts triggers and connector dispatch.
471    Orchestrator(OrchestratorArgs),
472    /// Run a pipeline against a Harn-native host module for fast iteration.
473    Playground(PlaygroundArgs),
474    /// Inspect persisted workflow run records.
475    Runs(RunsArgs),
476    /// Export, import, and validate portable Harn session bundles.
477    Session(SessionArgs),
478    /// Replay a persisted workflow run record.
479    Replay(ReplayArgs),
480    /// Evaluate a run record, run directory, or eval manifest.
481    Eval(EvalArgs),
482    /// Start the interactive REPL.
483    Repl,
484    /// Benchmark Harn execution, portable-kernel paths, or deterministic replay.
485    Bench(BenchArgs),
486    /// Pre-compile `.harn` sources into the content-addressed bytecode
487    /// cache so cold-start `harn run` for the same source skips parse
488    /// and compile and goes straight to bytecode load.
489    ///
490    /// `harn precompile path/` walks the directory and compiles every
491    /// `.harn` file; `harn precompile script.harn` compiles a single
492    /// file. Artifacts are written adjacent to each source as
493    /// `<name>.harnbc` by default; pass `--out DIR` to redirect them
494    /// into a sibling tree.
495    Precompile(PrecompileArgs),
496    /// Build or verify a `.harnpack` content-addressed run bundle.
497    ///
498    /// `harn pack <entrypoint>` walks the entrypoint's transitive imports,
499    /// links one closed program, snapshots the provider catalog and stdlib
500    /// pin, generates a minimal SBOM, and emits a deterministic tar.zst
501    /// container under `<entrypoint>.harnpack` (or `--out`).
502    ///
503    /// `harn pack verify <bundle.harnpack>` reads a bundle back, recomputes
504    /// its canonical hash, verifies the embedded Ed25519 signature (if any),
505    /// and cross-checks source and linked-artifact BLAKE3 identities against
506    /// the manifest.
507    /// Exits non-zero on any mismatch.
508    ///
509    /// `--upgrade <old.harnpack>` reads an existing bundle (v1 or v2) and
510    /// re-emits it under the v3 manifest, preserving the prior bundle's
511    /// workflow graph, triggers, and prompt capsules. `--exclude-secrets`
512    /// refuses to bundle paths that look like secrets (`.env`, `*.pem`,
513    /// `credentials*`, anything under `secrets/`).
514    Pack(PackArgs),
515    /// Render a .harn file as a Mermaid workflow graph.
516    Viz(VizArgs),
517    /// Install dependencies declared in harn.toml.
518    Install(InstallArgs),
519    /// Add a dependency to harn.toml.
520    Add(AddArgs),
521    /// Refresh one or more dependency lock entries.
522    Update(UpdateArgs),
523    /// Remove a dependency from harn.toml and harn.lock.
524    Remove(RemoveArgs),
525    /// Resolve dependencies and write harn.lock without materializing packages.
526    Lock,
527    /// Manage Harn package caches and integrity verification.
528    Package(PackageArgs),
529    /// Publish a package by tagging the source repo and opening a package-index PR.
530    Publish(PublishArgs),
531    /// List and inspect durable agent persona manifests.
532    Persona(PersonaArgs),
533    /// Postgres developer tooling (codegen Harn record types from migrations).
534    Pg(PgArgs),
535    /// Merge Captain transcript oracle and audit (#1013).
536    #[command(name = "merge-captain")]
537    MergeCaptain(MergeCaptainArgs),
538    /// List, install, recommend, and test configured LLM models.
539    Models(ModelsArgs),
540    /// Manage local LLM runtime lifecycle: enumerate, switch, and stop
541    /// Ollama, llama.cpp, MLX, and other OpenAI-compatible local servers.
542    Local(LocalArgs),
543    /// Inspect provider/model capabilities, catalog, and readiness.
544    Provider(ProviderArgs),
545    /// Read-only structural search + lint: run a pattern, rule, or rule pack
546    /// over a fileset and report matches or per-file counts (`--report-only`).
547    Scan(ScanArgs),
548    /// Apply a codemod rule's `fix` across a fileset. Dry-run by default
549    /// (unified diffs); `--apply` writes, safety- and capability-gated.
550    Codemod(CodemodArgs),
551    /// Author and test structural rules (`harn rule test` runs a rule's
552    /// inline-annotation fixtures).
553    Rule(RuleArgs),
554    /// One-shot agent_loop with a prompt. Routes through the configured
555    /// provider (or `HARN_LLM_PROVIDER=mock` for offline use).
556    #[command(name = "try")]
557    Try(TryArgs),
558    /// Manage and inspect Harn skills: corpus discovery (list/get/dump/
559    /// resolved/inspect/match/install/new) and provenance (sign/endorse/
560    /// verify/who-signed/key/trust).
561    Skill(SkillArgs),
562    /// Scaffold and inspect Harn-native custom tools.
563    Tool(ToolArgs),
564    /// Print the decorated version banner.
565    Version(VersionArgs),
566    /// Download and atomically replace the running `harn` binary with
567    /// the latest published GitHub release (or a specific tag via
568    /// `--version`). Verifies the archive against the release's
569    /// `SHA256SUMS` manifest before installing.
570    Upgrade(UpgradeArgs),
571    /// Regenerate docs/theme/harn-keywords.js from the live lexer + stdlib sets.
572    ///
573    /// Dev-only. Hidden from `--help` — invoke via
574    /// `cargo run -p harn-cli -- dump-highlight-keywords` or the
575    /// `make gen-highlight` target.
576    #[command(hide = true, name = "dump-highlight-keywords")]
577    DumpHighlightKeywords(DumpHighlightKeywordsArgs),
578    /// Regenerate the portable benchmark JSON Schema from the kernel-owned
579    /// receipt type and validation constants.
580    #[command(hide = true, name = "dump-portable-benchmark-schema")]
581    DumpPortableBenchmarkSchema(DumpPortableBenchmarkSchemaArgs),
582    /// Regenerate the VS Code `.harn.prompt` TextMate grammar from the live
583    /// prompt-template keyword, filter, and section vocabulary.
584    ///
585    /// Dev-only. Hidden from `--help` — invoke via
586    /// `cargo run -p harn-cli -- dump-prompt-grammar` or the
587    /// `make gen-prompt-grammar` target.
588    #[command(hide = true, name = "dump-prompt-grammar")]
589    DumpPromptGrammar(DumpPromptGrammarArgs),
590    /// Regenerate docs/llm/harn-triggers-quickref.md from the live trigger provider catalog.
591    ///
592    /// Dev-only. Hidden from `--help` — invoke via
593    /// `cargo run -p harn-cli -- dump-trigger-quickref` or the
594    /// `make gen-trigger-quickref` target.
595    #[command(hide = true, name = "dump-trigger-quickref")]
596    DumpTriggerQuickref(DumpTriggerQuickrefArgs),
597    /// Regenerate docs/src/connectors/parity-matrix.md from connector package manifests.
598    ///
599    /// Dev-only. Hidden from `--help` — invoke via
600    /// `cargo run -p harn-cli -- dump-connector-matrix` or the
601    /// `make gen-connector-matrix` target.
602    #[command(hide = true, name = "dump-connector-matrix")]
603    DumpConnectorMatrix(DumpConnectorMatrixArgs),
604    /// Regenerate Harn protocol schemas and TypeScript/Swift bindings.
605    ///
606    /// Dev-only. Hidden from `--help` — invoke via
607    /// `cargo run -p harn-cli -- dump-protocol-artifacts` or the
608    /// `make gen-protocol-artifacts` target.
609    #[command(hide = true, name = "dump-protocol-artifacts")]
610    DumpProtocolArtifacts(DumpProtocolArtifactsArgs),
611    /// Regenerate the Rust normalized-event structs from the canonical Harn
612    /// connector event schema module.
613    ///
614    /// Dev-only. Hidden from `--help` — invoke via
615    /// `cargo run -p harn-cli -- connector-schema-codegen` or the
616    /// `make gen-connector-schemas` target.
617    #[command(hide = true, name = "connector-schema-codegen")]
618    ConnectorSchemaCodegen(ConnectorSchemaCodegenArgs),
619    /// Regenerate the removed-global → typed-harness-path table that
620    /// `harn-parser` reads, from the runtime migration registry.
621    ///
622    /// Dev-only. Hidden from `--help` — invoke via
623    /// `cargo run -p harn-cli -- dump-harness-migrations` or the
624    /// `make gen-harness-migrations` target.
625    #[command(hide = true, name = "dump-harness-migrations")]
626    DumpHarnessMigrations(DumpHarnessMigrationsArgs),
627    /// Internal fixtures used by the conformance suite.
628    #[command(hide = true, name = "conformance-helper")]
629    ConformanceHelper(ConformanceHelperArgs),
630}
631
632#[cfg(test)]
633mod tests;
harn_cli/cli/mod.rs

harn_cli/cli/
mod.rs
