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

harn_cli/cli/
mod.rs
