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

harn_cli/cli/
mod.rs
