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

harn_cli/cli/
mod.rs
