harn_cli/cli/
mod.rs

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

harn_cli/cli/
mod.rs
