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

harn_cli/cli/
mod.rs
