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

harn_cli/cli/
mod.rs
