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

harn_cli/cli/
mod.rs
