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

harn_cli/cli/
mod.rs
