Crate agcli 

Agent-native CLI primitives for Rust.

This crate enforces an agent-first response model:

• JSON envelopes for every command
• HATEOAS next_actions for follow-up affordances
• self-documenting command tree from root/help
• NDJSON streaming helpers with terminal result/error events
• context-safe truncation helpers for large output

Example

use agcli::{AgentCli, Command, CommandOutput, ExecutionContext, NextAction};
use serde_json::json;

#[tokio::main]
async fn main() {
    let cli = AgentCli::new("ops", "Agent-native operations CLI")
        .command(
            Command::new("status", "System health")
                .usage("ops status")
                .handler(|_req, _ctx| Box::pin(async move {
                    Ok(CommandOutput::new(json!({ "healthy": true })).next_action(
                        NextAction::new("ops status", "Re-check health"),
                    ))
                })),
        );

    let mut ctx = ExecutionContext::default();
    let run = cli.run_argv_with_context(["ops", "status"], &mut ctx).await;
    assert_eq!(run.exit_code(), 0);
}

Structs

ActionParam

Metadata for a templated next_action parameter.

AgentCli

Agent-native CLI runtime.

AuditFinding

A single problem discovered by crate::AgentCli::audit.

AuditReport

The result of a static audit pass.

Check

A single named health check with the exit code to use if it fails.

CheckResult

Outcome of a single Check.

Command

CLI command definition.

CommandError

Error payload returned from a command handler.

CommandOutput

Success payload returned from a command handler.

CommandRequest

Runtime request passed to each command handler.

ErrorBody

Machine-readable error payload.

ErrorEnvelope

Error response envelope.

Execution

Executed CLI result wrapper.

ExecutionContext

Mutable state shared across command invocations.

ExitCode

Typed process exit codes for agent self-correction.

Invocation

Parsed command-line invocation.

NdjsonEmitter

Stateful NDJSON event emitter that enforces terminal result/error semantics.

NextAction

HATEOAS action template that tells an agent what to run next.

SuccessEnvelope

Success response envelope.

TruncatedEntries

Context-safe result for potentially large line-oriented output.

Enums

AuditSeverity

Severity of an AuditFinding.

CheckStatus

The three outcomes of a Check. Serialized into the doctor report as the lowercase status string on each check entry.

Envelope

Unified envelope enum.

FlushPolicy

Controls when the emitter flushes the underlying writer.

LogLevel

Log level for stream events.

ParseInvocationError

Invocation parser failure.

StepStatus

Step lifecycle status for stream events.

StreamEmitError

NDJSON emit failure.

StreamEvent

Typed NDJSON stream event.

Functions

parse_invocation

Parse argv into an Invocation without any boolean-flag schema.

parse_invocation_with_bool_flags

Parse argv into an Invocation, treating any flag for which is_bool returns true as a pure boolean (it never consumes the next token).

read_stdin

Read all of stdin to a string. Pairs with the --stdin convention so a handler can accept piped input: if req.wants_stdin() { read_stdin().await }.

reserved_flag_names

Every framework-reserved flag name (without the leading --), for runtime discovery. These names are reserved whenever AgentCli::reserved_flags is enabled (the default): the framework parses and acts on them on every command. select is a value flag; the others are parsed as booleans anywhere on the line.

truncate_lines_with_file

Truncate to the last max_lines lines and, when truncated, write the full output to a temp file (see TruncatedEntries for the tail/dropped semantics and the file’s ownership rules).