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

harn_cli/cli/
mod.rs
