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

harn_cli/cli/
mod.rs
