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

harn_cli/cli/
mod.rs
