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

harn_cli/cli/
mod.rs
