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 check;
15mod completions;
16mod config_cmd;
17mod connect;
18mod connector;
19mod contracts;
20mod crystallize;
21mod demo;
22mod doctor;
23mod dump;
24mod eval;
25mod explain;
26mod flow;
27mod init;
28mod lint_fmt;
29mod local;
30mod mcp;
31mod merge_captain;
32mod models;
33mod orchestrator;
34mod package;
35mod persona;
36mod playground;
37mod portal;
38mod precompile;
39mod profile;
40mod provider;
41mod providers;
42mod quickstart;
43mod run;
44mod runs;
45mod serve;
46mod session;
47mod skill;
48mod skills;
49mod supervisor;
50mod test;
51mod test_bench;
52mod tool;
53mod trace;
54mod trigger;
55mod trust;
56mod try_cmd;
57mod upgrade;
58mod util;
59mod verify;
60mod viz;
61mod watch;
62mod workflow;
63
64pub(crate) use bench::{BenchArgs, BenchCommand, BenchReplayArgs};
65pub(crate) use check::{CheckArgs, CheckOutputFormat};
66pub(crate) use completions::{CompletionShell, CompletionsArgs};
67pub(crate) use config_cmd::{ConfigArgs, ConfigCommand, ConfigInspectArgs, ConfigValidateArgs};
68pub(crate) use connect::{
69    ConnectApiKeyArgs, ConnectArgs, ConnectCommand, ConnectGenericArgs, ConnectGithubArgs,
70    ConnectLinearArgs, ConnectOAuthArgs, ConnectSetupPlanArgs, ConnectStatusArgs,
71};
72pub(crate) use connector::{
73    ConnectorArgs, ConnectorCheckArgs, ConnectorCommand, ConnectorTestArgs,
74};
75pub(crate) use contracts::{
76    ContractsArgs, ContractsBundleArgs, ContractsCommand, ContractsHostCapabilitiesArgs,
77    ContractsOutputArgs,
78};
79pub(crate) use crystallize::{
80    CrystallizeArgs, CrystallizeCommand, CrystallizeIngestArgs, CrystallizeShadowArgs,
81    CrystallizeValidateArgs,
82};
83pub(crate) use demo::DemoArgs;
84pub(crate) use doctor::DoctorArgs;
85pub(crate) use dump::{
86    DumpConnectorMatrixArgs, DumpHighlightKeywordsArgs, DumpProtocolArtifactsArgs,
87    DumpTriggerQuickrefArgs,
88};
89pub use eval::{
90    EvalArgs, EvalCommand, EvalPromptArgs, EvalPromptMode, EvalPromptOutput, EvalToolCallsArgs,
91    EvalToolCallsCommand, EvalToolCallsRegressionArgs,
92};
93pub(crate) use explain::ExplainArgs;
94pub(crate) use flow::{
95    FlowArchivistCommand, FlowArchivistScanArgs, FlowArgs, FlowCommand, FlowReplayAuditArgs,
96    FlowShipCommand, FlowShipWatchArgs,
97};
98pub(crate) use init::{InitArgs, NewArgs, ProjectTemplate};
99pub(crate) use lint_fmt::{FmtArgs, PathTargetsArgs};
100pub(crate) use local::{
101    LocalArgs, LocalCommand, LocalListArgs, LocalProfileArgs, LocalStatusArgs, LocalStopArgs,
102    LocalSwitchArgs,
103};
104pub(crate) use mcp::{McpArgs, McpCommand, McpLoginArgs, McpServeArgs, McpServerRefArgs};
105pub(crate) use merge_captain::{
106    MergeCaptainArgs, MergeCaptainAuditArgs, MergeCaptainAuditFormat, MergeCaptainBackendKind,
107    MergeCaptainCommand, MergeCaptainIterateArgs, MergeCaptainIterateFormat,
108    MergeCaptainLadderArgs, MergeCaptainLadderFormat, MergeCaptainMockCleanupArgs,
109    MergeCaptainMockCommand, MergeCaptainMockInitArgs, MergeCaptainMockServeArgs,
110    MergeCaptainMockStatusArgs, MergeCaptainMockStepArgs, MergeCaptainRunArgs,
111};
112pub(crate) use models::{
113    ModelRecommendArgs, ModelsArgs, ModelsCommand, ModelsInstallArgs, ModelsListArgs,
114    ModelsTestArgs,
115};
116pub(crate) use orchestrator::{
117    OrchestratorArgs, OrchestratorCommand, OrchestratorDeployArgs, OrchestratorDeployProvider,
118    OrchestratorDlqArgs, OrchestratorFireArgs, OrchestratorInspectArgs, OrchestratorLocalArgs,
119    OrchestratorLogFormat, OrchestratorQueueArgs, OrchestratorQueueCommand,
120    OrchestratorQueueDrainArgs, OrchestratorQueueLsArgs, OrchestratorQueuePurgeArgs,
121    OrchestratorRecoverArgs, OrchestratorReloadArgs, OrchestratorReplayArgs,
122    OrchestratorReplayOracleArgs, OrchestratorResumeArgs, OrchestratorServeArgs,
123    OrchestratorStatsArgs, OrchestratorTenantArgs, OrchestratorTenantCommand,
124    OrchestratorTenantCreateArgs, OrchestratorTenantDeleteArgs, OrchestratorTenantLsArgs,
125    OrchestratorTenantSuspendArgs,
126};
127pub(crate) use package::{
128    AddArgs, InstallArgs, PackageArgs, PackageArtifactsCommand, PackageCacheCommand,
129    PackageCommand, PublishArgs, RemoveArgs, UpdateArgs,
130};
131pub(crate) use persona::{
132    PersonaArgs, PersonaCheckArgs, PersonaCommand, PersonaControlArgs, PersonaDoctorArgs,
133    PersonaInspectArgs, PersonaListArgs, PersonaNewArgs, PersonaSpendArgs, PersonaStatusArgs,
134    PersonaSupervisionCommand, PersonaSupervisionTailArgs, PersonaTemplateKind, PersonaTickArgs,
135    PersonaTriggerArgs,
136};
137pub(crate) use playground::PlaygroundArgs;
138pub(crate) use portal::PortalArgs;
139pub use precompile::PrecompileArgs;
140pub(crate) use profile::ProfileArgs;
141pub(crate) use provider::{
142    ModelInfoArgs, ProviderCatalogArgs, ProviderProbeArgs, ProviderReadyArgs,
143    ProviderToolProbeArgs, ProviderToolProbeModeArg,
144};
145pub(crate) use providers::{
146    ProvidersArgs, ProvidersCommand, ProvidersExportArgs, ProvidersRefreshArgs,
147    ProvidersValidateArgs,
148};
149pub(crate) use quickstart::QuickstartArgs;
150pub(crate) use run::RunArgs;
151pub(crate) use runs::{ReplayArgs, RunsArgs, RunsCommand};
152pub(crate) use serve::{
153    A2aServeArgs, ApiServeArgs, McpServeTransport, ServeAcpArgs, ServeArgs, ServeCommand,
154    ServeMcpArgs, ServeTlsMode,
155};
156pub(crate) use session::{
157    SessionArgs, SessionCommand, SessionExportArgs, SessionImportArgs, SessionSchemaArgs,
158    SessionValidateArgs,
159};
160pub(crate) use skill::{
161    SkillArgs, SkillCommand, SkillEndorseArgs, SkillKeyCommand, SkillKeyGenerateArgs,
162    SkillSignArgs, SkillTrustAddArgs, SkillTrustCommand, SkillTrustListArgs, SkillVerifyArgs,
163    SkillWhoSignedArgs,
164};
165pub(crate) use skills::{
166    SkillsArgs, SkillsCommand, SkillsInspectArgs, SkillsInstallArgs, SkillsListArgs,
167    SkillsMatchArgs, SkillsNewArgs,
168};
169pub(crate) use supervisor::{
170    SupervisorArgs, SupervisorCommand, SupervisorDlqCommand, SupervisorDlqListArgs,
171    SupervisorDlqReplayArgs, SupervisorFireArgs, SupervisorInspectArgs, SupervisorListArgs,
172    SupervisorPauseArgs, SupervisorRecoverArgs, SupervisorReplayArgs, SupervisorResumeArgs,
173    SupervisorStartArgs, SupervisorStopArgs,
174};
175pub(crate) use test::TestArgs;
176pub(crate) use test_bench::{
177    TestBenchArgs, TestBenchCommand, TestBenchExportAnnotationsArgs, TestBenchFidelityArgs,
178    TestBenchReplayArgs, TestBenchRunArgs, TestBenchValidateAnnotationsArgs,
179};
180pub(crate) use tool::{ToolArgs, ToolCommand, ToolNewArgs};
181pub(crate) use trace::{TraceArgs, TraceCommand, TraceImportArgs};
182pub(crate) use trigger::{TriggerArgs, TriggerCancelArgs, TriggerCommand, TriggerReplayArgs};
183pub(crate) use try_cmd::TryArgs;
184pub(crate) use upgrade::UpgradeArgs;
185// `TrustOutcomeArg` / `TrustTierArg` are referenced from the cli
186// parser tests only; they're matched via destructuring elsewhere.
187#[allow(unused_imports)]
188pub(crate) use trust::{
189    TrustArgs, TrustCommand, TrustExportArgs, TrustOutcomeArg, TrustQueryArgs, TrustTierArg,
190    TrustVerifyChainArgs,
191};
192pub(crate) use verify::VerifyArgs;
193pub(crate) use viz::VizArgs;
194pub(crate) use watch::WatchArgs;
195pub(crate) use workflow::{
196    WorkflowArgs, WorkflowCommand, WorkflowFunctionToolsArgs, WorkflowNestedCeilingArgs,
197    WorkflowPatchApplyArgs, WorkflowPatchCommand, WorkflowPatchPreviewArgs,
198    WorkflowPatchValidateArgs,
199};
200
201use clap::{Parser, Subcommand};
202
203#[derive(Debug, Parser)]
204#[command(
205    name = "harn",
206    about = "The agent harness language",
207    version,
208    disable_help_subcommand = false,
209    arg_required_else_help = true
210)]
211pub(crate) struct Cli {
212    #[command(subcommand)]
213    pub command: Option<Command>,
214}
215
216#[derive(Debug, Subcommand)]
217pub(crate) enum Command {
218    /// Execute a .harn file or an inline expression.
219    #[command(long_about = "\
220Execute a .harn file or an inline expression.
221
222USAGE
223    harn run script.harn
224    harn run -e 'println(\"hello\")'
225    harn run script.harn -- arg1 arg2   (script reads `argv` as list<string>)
226
227CONCURRENCY
228    Harn supports first-class concurrency primitives:
229      - spawn { ... }         — launch a task, return a handle
230      - parallel each LIST    — concurrent map
231      - parallel settle LIST  — concurrent map, collect Ok/Err
232      - parallel N            — N-way fan-out
233      - with { max_concurrent: N }  — cap in-flight workers
234      - channels, retry, select
235    https://harnlang.com/concurrency.html
236
237LLM THROTTLING
238    Providers can be rate-limited via `rpm:` in harn.toml / providers.toml
239    or via `HARN_RATE_LIMIT_<PROVIDER>=N`. Rate limits control throughput
240    (RPM); `max_concurrent` on `parallel` caps simultaneous in-flight jobs.
241
242SCRIPTING
243    LLM-readable one-pager: https://harnlang.com/docs/llm/harn-quickref.html
244    Human cheatsheet:       https://harnlang.com/scripting-cheatsheet.html
245    Full docs:              https://harnlang.com/
246")]
247    Run(RunArgs),
248    /// Type-check .harn files or directories without executing them.
249    Check(CheckArgs),
250    /// Inspect, validate, and emit schemas for layered Harn runtime config.
251    Config(ConfigArgs),
252    /// Explain the control-flow path that violates a Harn invariant
253    /// (e.g. `fs.writes`, `approval.reachability`) for a specific
254    /// function or trigger handler.
255    Explain(ExplainArgs),
256    /// Export machine-readable Harn contracts and bundle manifests.
257    Contracts(ContractsArgs),
258    /// Lint .harn files or directories for common issues.
259    Lint(PathTargetsArgs),
260    /// Format .harn files or directories.
261    Fmt(FmtArgs),
262    /// Run user tests or the conformance suite.
263    Test(TestArgs),
264    /// Run a .harn script under a hermetic testbench (paused clock,
265    /// optional LLM/process tapes, fs overlay, deny-by-default network).
266    #[command(name = "test-bench")]
267    TestBench(TestBenchArgs),
268    /// Scaffold a new project with harn.toml.
269    Init(InitArgs),
270    /// Scaffold a new project, package, or connector from a starter template.
271    New(NewArgs),
272    /// Diagnose the local Harn environment: toolchain version, configured
273    /// LLM providers and credentials, MCP server reachability, file
274    /// permissions on `~/.harn`, and project manifest health. Reports
275    /// each check as ok/warn/fail with a suggested fix.
276    Doctor(DoctorArgs),
277    /// Configure a starter Harn project and LLM provider settings.
278    Quickstart(QuickstartArgs),
279    /// Run a bundled offline demo scenario to see Harn in action without
280    /// API keys. `harn demo` lists scenarios; `harn demo <id>` runs one.
281    Demo(DemoArgs),
282    /// Register outbound connector resources with a provider.
283    Connect(Box<ConnectArgs>),
284    /// Validate pure-Harn connector packages against the connector contract.
285    Connector(ConnectorArgs),
286    /// Serve a Harn workflow over a transport adapter.
287    Serve(ServeArgs),
288    /// Manage remote MCP OAuth credentials and status.
289    Mcp(McpArgs),
290    /// Watch a .harn file and re-run it on changes.
291    Watch(WatchArgs),
292    /// Launch the local Harn observability portal.
293    Portal(PortalArgs),
294    /// Replay and inspect historical trigger dispatches from the event log.
295    Trigger(TriggerArgs),
296    /// Inspect Harn Flow atom, slice, and predicate audit state.
297    Flow(FlowArgs),
298    /// Validate, preview, and run portable workflow bundles.
299    Workflow(WorkflowArgs),
300    /// Control local durable workflow automations for trusted hosts.
301    Supervisor(SupervisorArgs),
302    /// Import third-party eval traces into replayable Harn fixtures.
303    Trace(TraceArgs),
304    /// Mine repeated traces into a reviewable deterministic Harn workflow candidate.
305    Crystallize(CrystallizeArgs),
306    /// Query and manage trust-graph autonomy state.
307    Trust(TrustArgs),
308    /// Alias for `harn trust`. Query and verify trust-graph autonomy state.
309    #[command(name = "trust-graph")]
310    TrustGraph(TrustArgs),
311    /// Verify a signed Harn provenance receipt.
312    Verify(VerifyArgs),
313    /// Print shell completion script to stdout.
314    Completions(CompletionsArgs),
315    /// Start the orchestrator process that hosts triggers and connector dispatch.
316    Orchestrator(OrchestratorArgs),
317    /// Run a pipeline against a Harn-native host module for fast iteration.
318    Playground(PlaygroundArgs),
319    /// Inspect persisted workflow run records.
320    Runs(RunsArgs),
321    /// Export, import, and validate portable Harn session bundles.
322    Session(SessionArgs),
323    /// Replay a persisted workflow run record.
324    Replay(ReplayArgs),
325    /// Evaluate a run record, run directory, or eval manifest.
326    Eval(EvalArgs),
327    /// Start the interactive REPL.
328    Repl,
329    /// Benchmark a .harn pipeline over repeated runs.
330    Bench(BenchArgs),
331    /// Pre-compile `.harn` sources into the content-addressed bytecode
332    /// cache so cold-start `harn run` for the same source skips parse
333    /// and compile and goes straight to bytecode load.
334    ///
335    /// `harn precompile path/` walks the directory and compiles every
336    /// `.harn` file; `harn precompile script.harn` compiles a single
337    /// file. Artifacts are written adjacent to each source as
338    /// `<name>.harnbc` by default; pass `--out DIR` to redirect them
339    /// into a sibling tree.
340    Precompile(PrecompileArgs),
341    /// Render a .harn file as a Mermaid workflow graph.
342    Viz(VizArgs),
343    /// Install dependencies declared in harn.toml.
344    Install(InstallArgs),
345    /// Add a dependency to harn.toml.
346    Add(AddArgs),
347    /// Refresh one or more dependency lock entries.
348    Update(UpdateArgs),
349    /// Remove a dependency from harn.toml and harn.lock.
350    Remove(RemoveArgs),
351    /// Resolve dependencies and write harn.lock without materializing packages.
352    Lock,
353    /// Manage Harn package caches and integrity verification.
354    Package(PackageArgs),
355    /// Prepare a package manifest and bundle for publication. Validates
356    /// `harn.toml` and produces a publishable archive locally; remote
357    /// registry submission is not yet implemented (the resulting
358    /// archive can be installed via `harn add <repo-or-path>` in the
359    /// meantime).
360    Publish(PublishArgs),
361    /// List and inspect durable agent persona manifests.
362    Persona(PersonaArgs),
363    /// Merge Captain transcript oracle and audit (#1013).
364    #[command(name = "merge-captain")]
365    MergeCaptain(MergeCaptainArgs),
366    /// Print resolved metadata for a model alias or model id as JSON.
367    ModelInfo(ModelInfoArgs),
368    /// List, install, recommend, and test configured LLM models.
369    Models(ModelsArgs),
370    /// Manage local LLM runtime lifecycle: enumerate, switch, and stop
371    /// Ollama, llama.cpp, MLX, and other OpenAI-compatible local servers.
372    Local(LocalArgs),
373    /// Validate and generate provider/model catalog artifacts.
374    Providers(ProvidersArgs),
375    /// Print the provider/model catalog Harn loaded as JSON.
376    ProviderCatalog(ProviderCatalogArgs),
377    /// Probe a provider's /models endpoint and optionally verify a served model.
378    ProviderReady(ProviderReadyArgs),
379    /// Snapshot a provider: readiness, served models, loaded models with
380    /// memory/context details. Designed for eval pipelines that need a
381    /// stable telemetry envelope per provider.
382    ProviderProbe(ProviderProbeArgs),
383    /// Run one-tool provider conformance and classify native/text fallback.
384    ProviderToolProbe(ProviderToolProbeArgs),
385    /// One-shot agent_loop with a prompt. Routes through the configured
386    /// provider (or `HARN_LLM_PROVIDER=mock` for offline use).
387    #[command(name = "try")]
388    Try(TryArgs),
389    /// Manage and inspect Harn skills (list, inspect, match, install, new).
390    Skills(SkillsArgs),
391    /// Manage skill provenance: keys, signatures, verification, and trust policy.
392    Skill(SkillArgs),
393    /// Scaffold and inspect Harn-native custom tools.
394    Tool(ToolArgs),
395    /// Print the decorated version banner.
396    Version,
397    /// Download and atomically replace the running `harn` binary with
398    /// the latest published GitHub release (or a specific tag via
399    /// `--version`). Verifies the archive against the release's
400    /// `SHA256SUMS` manifest before installing.
401    Upgrade(UpgradeArgs),
402    /// Regenerate docs/theme/harn-keywords.js from the live lexer + stdlib sets.
403    ///
404    /// Dev-only. Hidden from `--help` — invoke via
405    /// `cargo run -p harn-cli -- dump-highlight-keywords` or the
406    /// `make gen-highlight` target.
407    #[command(hide = true, name = "dump-highlight-keywords")]
408    DumpHighlightKeywords(DumpHighlightKeywordsArgs),
409    /// Regenerate docs/llm/harn-triggers-quickref.md from the live trigger provider catalog.
410    ///
411    /// Dev-only. Hidden from `--help` — invoke via
412    /// `cargo run -p harn-cli -- dump-trigger-quickref` or the
413    /// `make gen-trigger-quickref` target.
414    #[command(hide = true, name = "dump-trigger-quickref")]
415    DumpTriggerQuickref(DumpTriggerQuickrefArgs),
416    /// Regenerate docs/src/connectors/parity-matrix.md from connector package manifests.
417    ///
418    /// Dev-only. Hidden from `--help` — invoke via
419    /// `cargo run -p harn-cli -- dump-connector-matrix` or the
420    /// `make gen-connector-matrix` target.
421    #[command(hide = true, name = "dump-connector-matrix")]
422    DumpConnectorMatrix(DumpConnectorMatrixArgs),
423    /// Regenerate Harn protocol schemas and TypeScript/Swift bindings.
424    ///
425    /// Dev-only. Hidden from `--help` — invoke via
426    /// `cargo run -p harn-cli -- dump-protocol-artifacts` or the
427    /// `make gen-protocol-artifacts` target.
428    #[command(hide = true, name = "dump-protocol-artifacts")]
429    DumpProtocolArtifacts(DumpProtocolArtifactsArgs),
430}
431
432#[cfg(test)]
433mod tests;
harn_cli/cli/mod.rs

harn_cli/cli/
mod.rs
