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

harn_cli/cli/
mod.rs
