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 portal;
52mod precompile;
53mod profile;
54mod provider;
55mod providers;
56mod quickstart;
57mod routes;
58mod rule;
59mod run;
60pub(crate) mod runs;
61mod sandbox;
62mod scan;
63mod serve;
64mod session;
65mod skill;
66mod skills;
67mod supervisor;
68mod test;
69mod test_bench;
70mod time;
71mod tool;
72mod trace;
73mod trigger;
74mod trust;
75mod try_cmd;
76mod upgrade;
77mod usage;
78mod util;
79mod verify;
80mod version;
81mod viz;
82mod watch;
83mod workflow;
84
85pub(crate) use app::{AppArgs, AppCommand};
86pub(crate) use bench::{
87    BenchArgs, BenchCommand, BenchPortableArgs, BenchReplayArgs, PortableEntryKindArg,
88};
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, DumpHighlightKeywordsArgs,
118    DumpPortableBenchmarkSchemaArgs, DumpPromptGrammarArgs, DumpProtocolArtifactsArgs,
119    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 portal::PortalArgs;
198pub use precompile::PrecompileArgs;
199pub(crate) use profile::ProfileArgs;
200pub(crate) use provider::ProviderToolProbeFormatArg;
201#[cfg(test)]
202pub(crate) use provider::ProviderToolProbeModeArg;
203pub(crate) use provider::{
204    refresh_provider_catalog_if_requested, ProviderArgs, ProviderCacheProbeArgs,
205    ProviderCapabilitiesArgs, ProviderCapabilitiesCommand, ProviderCapabilitiesPromoteFromEvalArgs,
206    ProviderCommand, ProviderDispatchAuditArgs, ProviderDispatchAuditVariantArg,
207    ProviderDispatchExplainArgs, ProviderLimitsArgs, ProviderProbeArgs, ProviderToolCalibrateArgs,
208    ProviderToolProbeArgs, ProviderToolProbeAuditArgs, ProviderToolProbeCaseArg,
209    ProviderToolScorecardArgs,
210};
211pub(crate) use providers::{
212    ProviderCatalogCommand, ProvidersExportArgs, ProvidersGenerateArgs, ProvidersMatrixArgs,
213    ProvidersOverlayAuditArgs, ProvidersRecommendArgs, ProvidersRefreshArgs, ProvidersSupportArgs,
214    ProvidersValidateArgs,
215};
216pub(crate) use quickstart::QuickstartArgs;
217pub(crate) use routes::RoutesArgs;
218pub(crate) use rule::{RuleArgs, RuleCommand, RuleTestArgs};
219pub(crate) use run::RunArgs;
220pub(crate) use runs::{run_runs_command, ReplayArgs, RunsArgs, RunsExportTrainingArgs};
221pub(crate) use sandbox::SandboxArgs;
222pub(crate) use scan::ScanArgs;
223pub(crate) use serve::{
224    A2aServeArgs, AcpServeTransport, ApiServeArgs, McpServeTransport, ServeAcpArgs, ServeArgs,
225    ServeCommand, ServeMcpArgs, ServeObsMode, ServeTlsMode, SiteServeArgs, WorkerServeArgs,
226};
227pub(crate) use session::{
228    SessionArgs, SessionCheckpointArgs, SessionCommand, SessionExportArgs, SessionImportArgs,
229    SessionSchemaArgs, SessionValidateArgs,
230};
231pub(crate) use skill::{
232    SkillArgs, SkillCommand, SkillEndorseArgs, SkillKeyCommand, SkillKeyGenerateArgs,
233    SkillSignArgs, SkillTrustAddArgs, SkillTrustCommand, SkillTrustListArgs, SkillVerifyArgs,
234    SkillWhoSignedArgs,
235};
236pub(crate) use skills::{
237    SkillsDumpArgs, SkillsGetArgs, SkillsInspectArgs, SkillsInstallArgs, SkillsListArgs,
238    SkillsMatchArgs, SkillsNewArgs, SkillsResolvedArgs, SkillsValidateArgs,
239};
240pub(crate) use supervisor::{
241    SupervisorArgs, SupervisorCommand, SupervisorDlqCommand, SupervisorDlqListArgs,
242    SupervisorDlqReplayArgs, SupervisorFireArgs, SupervisorInspectArgs, SupervisorListArgs,
243    SupervisorPauseArgs, SupervisorRecoverArgs, SupervisorReplayArgs, SupervisorResumeArgs,
244    SupervisorStartArgs, SupervisorStopArgs,
245};
246pub(crate) use test::TestArgs;
247pub(crate) use test_bench::{
248    TestBenchArgs, TestBenchCommand, TestBenchExportAnnotationsArgs, TestBenchFidelityArgs,
249    TestBenchReplayArgs, TestBenchRunArgs, TestBenchValidateAnnotationsArgs,
250};
251pub(crate) use time::{TimeArgs, TimeCommand, TimeRunArgs};
252pub(crate) use tool::{ToolArgs, ToolCommand, ToolNewArgs};
253pub(crate) use trace::{TraceArgs, TraceCommand, TraceImportArgs};
254pub(crate) use trigger::{TriggerArgs, TriggerCancelArgs, TriggerCommand, TriggerReplayArgs};
255pub(crate) use try_cmd::TryArgs;
256pub(crate) use upgrade::UpgradeArgs;
257pub(crate) use usage::{UsageArgs, UsageGroupBy};
258// `TrustOutcomeArg` / `TrustTierArg` are referenced from the cli
259// parser tests only; they're matched via destructuring elsewhere.
260#[allow(unused_imports)]
261pub(crate) use trust::{
262    TrustArgs, TrustCommand, TrustExportArgs, TrustOutcomeArg, TrustQueryArgs, TrustTierArg,
263    TrustVerifyChainArgs,
264};
265pub(crate) use verify::VerifyArgs;
266pub(crate) use version::VersionArgs;
267pub(crate) use viz::VizArgs;
268pub(crate) use watch::WatchArgs;
269pub(crate) use workflow::{
270    WorkflowArgs, WorkflowCommand, WorkflowFunctionToolsArgs, WorkflowNestedCeilingArgs,
271    WorkflowPatchApplyArgs, WorkflowPatchCommand, WorkflowPatchPreviewArgs,
272    WorkflowPatchValidateArgs,
273};
274
275use clap::{Parser, Subcommand};
276
277#[derive(Debug, Parser)]
278#[command(
279    name = "harn",
280    about = "The agent harness language",
281    version,
282    disable_help_subcommand = false,
283    arg_required_else_help = true
284)]
285pub(crate) struct Cli {
286    /// Emit the JSON-schema catalog for every `harn` subcommand that
287    /// exposes a structured `--json` envelope. Pair with
288    /// `--command <name>` to print just one entry.
289    #[arg(long = "json-schemas", global = false)]
290    pub json_schemas: bool,
291
292    /// When combined with `--json-schemas`, restrict the catalog to a
293    /// single command name (e.g. `--command run`).
294    #[arg(
295        long = "command",
296        requires = "json_schemas",
297        value_name = "COMMAND",
298        global = false
299    )]
300    pub schema_command: Option<String>,
301
302    #[command(subcommand)]
303    pub command: Option<Command>,
304}
305
306#[derive(Debug, Subcommand)]
307pub(crate) enum Command {
308    /// Build and run interactive AI applications written in Harn.
309    App(AppArgs),
310    /// Execute a .harn file or an inline expression.
311    #[command(long_about = "\
312Execute a .harn file or an inline expression.
313
314USAGE
315    harn run script.harn
316    harn run -e 'log(\"hello\")'
317    harn run script.harn -- arg1 arg2   (script reads `argv` as list<string>)
318
319CONCURRENCY
320    Harn supports first-class concurrency primitives:
321      - spawn { ... }         — launch a task, return a handle
322      - parallel each LIST    — concurrent map
323      - parallel settle LIST  — concurrent map, collect Ok/Err
324      - parallel N            — N-way fan-out
325      - with { max_concurrent: N }  — cap in-flight workers
326      - channels, retry, select
327    https://harnlang.com/concurrency.html
328
329LLM THROTTLING
330    Providers can be rate-limited via `rpm:` in harn.toml / providers.toml
331    or via `HARN_RATE_LIMIT_<PROVIDER>=N`. Rate limits control throughput
332    (RPM); `max_concurrent` on `parallel` caps simultaneous in-flight jobs.
333
334SCRIPTING
335    LLM-readable one-pager: https://harnlang.com/docs/llm/harn-quickref.html
336    Human cheatsheet:       https://harnlang.com/scripting-cheatsheet.html
337    Full docs:              https://harnlang.com/
338")]
339    Run(RunArgs),
340    /// Type-check .harn files or directories without executing them.
341    Check(CheckArgs),
342    /// Parse a .harn file and print its AST.
343    Parse(ParseArgs),
344    /// Tokenize a .harn file and print lexer tokens.
345    Tokens(TokensArgs),
346    /// Inspect, validate, and emit schemas for layered Harn runtime config.
347    Config(ConfigArgs),
348    /// Explain a diagnostic. Pass a stable `HARN-<CAT>-<NNN>` code
349    /// (optionally with `--json` for the structured envelope), or the
350    /// legacy `--invariant <NAME> <FUNCTION> <FILE>` form to walk the
351    /// control-flow path behind a Harn invariant violation.
352    Explain(ExplainArgs),
353    /// Plan or apply repair-bearing diagnostics under an explicit safety ceiling.
354    Fix(FixArgs),
355    /// Export machine-readable Harn contracts and bundle manifests.
356    Contracts(ContractsArgs),
357    /// Lint .harn files or directories for common issues.
358    Lint(PathTargetsArgs),
359    /// Format .harn files or directories.
360    Fmt(FmtArgs),
361    /// Manage downloadable on-device injection-detection models (Layer 2).
362    Guard(GuardArgs),
363    /// Run user tests or the conformance suite.
364    Test(TestArgs),
365    /// Run a .harn script under a hermetic testbench (paused clock,
366    /// optional LLM/process tapes, fs overlay, deny-by-default network).
367    #[command(name = "test-bench")]
368    TestBench(TestBenchArgs),
369    /// Instrument a wrapped subcommand with phase-level wall-clock
370    /// timing (parse, typecheck, bytecode compile + cache hit/miss,
371    /// run setup, run main) plus per-LLM-call and per-tool-call
372    /// latency. Pair with `--json` for an agent-readable envelope.
373    Time(TimeArgs),
374    /// Scaffold a new project with harn.toml.
375    Init(InitArgs),
376    /// Scaffold a new project, package, or connector from a starter template.
377    New(NewArgs),
378    /// Diagnose the local Harn environment: toolchain version, configured
379    /// LLM providers and credentials, MCP server reachability, file
380    /// permissions on `~/.harn`, and project manifest health. Reports
381    /// each check as ok/warn/fail with a suggested fix.
382    Doctor(DoctorArgs),
383    /// Coordinate scarce machine resources through typed host leases.
384    Host(HostArgs),
385    /// Configure a starter Harn project and LLM provider settings.
386    Quickstart(QuickstartArgs),
387    /// Run a bundled offline demo scenario to see Harn in action without
388    /// API keys. `harn demo` lists scenarios; `harn demo <id>` runs one.
389    Demo(DemoArgs),
390    /// Register outbound connector resources with a provider.
391    Connect(Box<ConnectArgs>),
392    /// Validate pure-Harn connector packages against the connector contract.
393    Connector(ConnectorArgs),
394    /// Serve a Harn workflow over a transport adapter.
395    Serve(ServeArgs),
396    /// Manage remote MCP OAuth credentials and status.
397    Mcp(McpArgs),
398    /// Launch the Harn debug adapter (DAP) over stdio.
399    ///
400    /// Speaks the Debug Adapter Protocol on stdin/stdout so an editor — or a
401    /// scripted DAP client — can set breakpoints, step, and inspect variables
402    /// in a `.harn` program. This is the same server the `harn-dap` binary
403    /// alias runs; the subcommand makes it reachable with just `harn` on PATH.
404    Dap(DapArgs),
405    /// Watch a .harn file and re-run it on changes.
406    Watch(WatchArgs),
407    /// Watch a Harn project and re-typecheck only the modules whose
408    /// public interface fingerprint actually changed.
409    ///
410    /// USAGE
411    ///     harn dev --watch [<root>]
412    ///     harn dev --watch --json
413    ///     harn dev --watch --with-tests
414    ///
415    /// On each file change, the changed module's interface fingerprint
416    /// (BLAKE3 of types + signatures + `pub import` re-exports) is
417    /// recomputed. If it matches the previous fingerprint, only that
418    /// module is re-checked. If it changed, every transitive importer
419    /// is invalidated and re-checked. `--with-tests` extends the loop
420    /// to also re-run `test_*` / `@test`-attributed pipelines in
421    /// every invalidated module.
422    Dev(DevArgs),
423    /// Launch the local Harn observability portal.
424    Portal(PortalArgs),
425    /// Replay and inspect historical trigger dispatches from the event log.
426    Trigger(TriggerArgs),
427    /// Statically enumerate declared trigger routes and their requirements.
428    Routes(RoutesArgs),
429    /// Aggregate LLM spend/usage analytics from the local event log's
430    /// `provider_call_response` records: cost, tokens, and prompt-cache
431    /// efficiency rolled up by provider, model, or a day/week/month
432    /// time series. Reuses the runtime-computed `cost_usd` — no pricing
433    /// is recomputed. Pair with `--json` for an agent-readable envelope.
434    Usage(UsageArgs),
435    /// Statically enumerate modules, symbols, imports, capabilities, effects, and host calls.
436    Graph(GraphArgs),
437    /// Render Markdown API reference docs for a Harn file or project's `pub`
438    /// symbols (functions, consts, types, enums, structs), drawn from their
439    /// HarnDoc comments: signature, description, parameters, `@effects`,
440    /// `@errors`, and return type. Prints to stdout by default; pass
441    /// `--output <file>` to write a file (e.g. `docs/api.md`).
442    Doc(DocArgs),
443    /// Inspect Harn Flow atom, slice, and predicate audit state.
444    Flow(FlowArgs),
445    /// Evaluate harn-canon invariant packs against changed files.
446    Canon(CanonArgs),
447    /// Validate, preview, and run portable workflow bundles.
448    Workflow(WorkflowArgs),
449    /// Control local durable workflow automations for trusted hosts.
450    Supervisor(SupervisorArgs),
451    /// Import third-party eval traces into replayable Harn fixtures.
452    Trace(TraceArgs),
453    /// Mine repeated traces into a reviewable deterministic Harn workflow candidate.
454    Crystallize(CrystallizeArgs),
455    /// Query and manage trust-graph autonomy state.
456    Trust(TrustArgs),
457    /// Verify a signed Harn provenance receipt.
458    Verify(VerifyArgs),
459    /// Print shell completion script to stdout.
460    Completion(CompletionArgs),
461    /// Start the orchestrator process that hosts triggers and connector dispatch.
462    Orchestrator(OrchestratorArgs),
463    /// Run a pipeline against a Harn-native host module for fast iteration.
464    Playground(PlaygroundArgs),
465    /// Inspect persisted workflow run records.
466    Runs(RunsArgs),
467    /// Export, import, and validate portable Harn session bundles.
468    Session(SessionArgs),
469    /// Replay a persisted workflow run record.
470    Replay(ReplayArgs),
471    /// Evaluate a run record, run directory, or eval manifest.
472    Eval(EvalArgs),
473    /// Start the interactive REPL.
474    Repl,
475    /// Benchmark Harn execution, portable-kernel paths, or deterministic replay.
476    Bench(BenchArgs),
477    /// Pre-compile `.harn` sources into the content-addressed bytecode
478    /// cache so cold-start `harn run` for the same source skips parse
479    /// and compile and goes straight to bytecode load.
480    ///
481    /// `harn precompile path/` walks the directory and compiles every
482    /// `.harn` file; `harn precompile script.harn` compiles a single
483    /// file. Artifacts are written adjacent to each source as
484    /// `<name>.harnbc` by default; pass `--out DIR` to redirect them
485    /// into a sibling tree.
486    Precompile(PrecompileArgs),
487    /// Build or verify a `.harnpack` content-addressed run bundle.
488    ///
489    /// `harn pack <entrypoint>` walks the entrypoint's transitive imports,
490    /// precompiles every module, snapshots the provider catalog and
491    /// stdlib pin, generates a minimal SBOM, and emits a deterministic
492    /// tar.zst container under `<entrypoint>.harnpack` (or `--out`).
493    ///
494    /// `harn pack verify <bundle.harnpack>` reads a bundle back, recomputes
495    /// its canonical hash, verifies the embedded Ed25519 signature (if any),
496    /// and cross-checks every per-module BLAKE3 against the manifest.
497    /// Exits non-zero on any mismatch.
498    ///
499    /// `--upgrade <old.harnpack>` reads an existing bundle (v1 or v2) and
500    /// re-emits it under the v2 manifest, preserving the prior bundle's
501    /// workflow graph, triggers, and prompt capsules. `--exclude-secrets`
502    /// refuses to bundle paths that look like secrets (`.env`, `*.pem`,
503    /// `credentials*`, anything under `secrets/`).
504    Pack(PackArgs),
505    /// Render a .harn file as a Mermaid workflow graph.
506    Viz(VizArgs),
507    /// Install dependencies declared in harn.toml.
508    Install(InstallArgs),
509    /// Add a dependency to harn.toml.
510    Add(AddArgs),
511    /// Refresh one or more dependency lock entries.
512    Update(UpdateArgs),
513    /// Remove a dependency from harn.toml and harn.lock.
514    Remove(RemoveArgs),
515    /// Resolve dependencies and write harn.lock without materializing packages.
516    Lock,
517    /// Manage Harn package caches and integrity verification.
518    Package(PackageArgs),
519    /// Publish a package by tagging the source repo and opening a package-index PR.
520    Publish(PublishArgs),
521    /// List and inspect durable agent persona manifests.
522    Persona(PersonaArgs),
523    /// Postgres developer tooling (codegen Harn record types from migrations).
524    Pg(PgArgs),
525    /// Merge Captain transcript oracle and audit (#1013).
526    #[command(name = "merge-captain")]
527    MergeCaptain(MergeCaptainArgs),
528    /// List, install, recommend, and test configured LLM models.
529    Models(ModelsArgs),
530    /// Manage local LLM runtime lifecycle: enumerate, switch, and stop
531    /// Ollama, llama.cpp, MLX, and other OpenAI-compatible local servers.
532    Local(LocalArgs),
533    /// Inspect provider/model capabilities, catalog, and readiness.
534    Provider(ProviderArgs),
535    /// Read-only structural search + lint: run a pattern, rule, or rule pack
536    /// over a fileset and report matches or per-file counts (`--report-only`).
537    Scan(ScanArgs),
538    /// Apply a codemod rule's `fix` across a fileset. Dry-run by default
539    /// (unified diffs); `--apply` writes, safety- and capability-gated.
540    Codemod(CodemodArgs),
541    /// Author and test structural rules (`harn rule test` runs a rule's
542    /// inline-annotation fixtures).
543    Rule(RuleArgs),
544    /// One-shot agent_loop with a prompt. Routes through the configured
545    /// provider (or `HARN_LLM_PROVIDER=mock` for offline use).
546    #[command(name = "try")]
547    Try(TryArgs),
548    /// Manage and inspect Harn skills: corpus discovery (list/get/dump/
549    /// resolved/inspect/match/install/new) and provenance (sign/endorse/
550    /// verify/who-signed/key/trust).
551    Skill(SkillArgs),
552    /// Scaffold and inspect Harn-native custom tools.
553    Tool(ToolArgs),
554    /// Print the decorated version banner.
555    Version(VersionArgs),
556    /// Download and atomically replace the running `harn` binary with
557    /// the latest published GitHub release (or a specific tag via
558    /// `--version`). Verifies the archive against the release's
559    /// `SHA256SUMS` manifest before installing.
560    Upgrade(UpgradeArgs),
561    /// Regenerate docs/theme/harn-keywords.js from the live lexer + stdlib sets.
562    ///
563    /// Dev-only. Hidden from `--help` — invoke via
564    /// `cargo run -p harn-cli -- dump-highlight-keywords` or the
565    /// `make gen-highlight` target.
566    #[command(hide = true, name = "dump-highlight-keywords")]
567    DumpHighlightKeywords(DumpHighlightKeywordsArgs),
568    /// Regenerate the portable benchmark JSON Schema from the kernel-owned
569    /// receipt type and validation constants.
570    #[command(hide = true, name = "dump-portable-benchmark-schema")]
571    DumpPortableBenchmarkSchema(DumpPortableBenchmarkSchemaArgs),
572    /// Regenerate the VS Code `.harn.prompt` TextMate grammar from the live
573    /// prompt-template keyword, filter, and section vocabulary.
574    ///
575    /// Dev-only. Hidden from `--help` — invoke via
576    /// `cargo run -p harn-cli -- dump-prompt-grammar` or the
577    /// `make gen-prompt-grammar` target.
578    #[command(hide = true, name = "dump-prompt-grammar")]
579    DumpPromptGrammar(DumpPromptGrammarArgs),
580    /// Regenerate docs/llm/harn-triggers-quickref.md from the live trigger provider catalog.
581    ///
582    /// Dev-only. Hidden from `--help` — invoke via
583    /// `cargo run -p harn-cli -- dump-trigger-quickref` or the
584    /// `make gen-trigger-quickref` target.
585    #[command(hide = true, name = "dump-trigger-quickref")]
586    DumpTriggerQuickref(DumpTriggerQuickrefArgs),
587    /// Regenerate docs/src/connectors/parity-matrix.md from connector package manifests.
588    ///
589    /// Dev-only. Hidden from `--help` — invoke via
590    /// `cargo run -p harn-cli -- dump-connector-matrix` or the
591    /// `make gen-connector-matrix` target.
592    #[command(hide = true, name = "dump-connector-matrix")]
593    DumpConnectorMatrix(DumpConnectorMatrixArgs),
594    /// Regenerate Harn protocol schemas and TypeScript/Swift bindings.
595    ///
596    /// Dev-only. Hidden from `--help` — invoke via
597    /// `cargo run -p harn-cli -- dump-protocol-artifacts` or the
598    /// `make gen-protocol-artifacts` target.
599    #[command(hide = true, name = "dump-protocol-artifacts")]
600    DumpProtocolArtifacts(DumpProtocolArtifactsArgs),
601    /// Regenerate the Rust normalized-event structs from the canonical Harn
602    /// connector event schema module.
603    ///
604    /// Dev-only. Hidden from `--help` — invoke via
605    /// `cargo run -p harn-cli -- connector-schema-codegen` or the
606    /// `make gen-connector-schemas` target.
607    #[command(hide = true, name = "connector-schema-codegen")]
608    ConnectorSchemaCodegen(ConnectorSchemaCodegenArgs),
609    /// Internal fixtures used by the conformance suite.
610    #[command(hide = true, name = "conformance-helper")]
611    ConformanceHelper(ConformanceHelperArgs),
612}
613
614#[cfg(test)]
615mod tests;
harn_cli/cli/mod.rs

harn_cli/cli/
mod.rs
