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

harn_cli/cli/
mod.rs
