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

harn_cli/cli/
mod.rs
