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

harn_cli/cli/
mod.rs
