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

harn_cli/cli/
mod.rs
