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

harn_cli/cli/
mod.rs
