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;

let cli = AgentCli::new("ops", "Agent-native operations CLI")
    .command(
        Command::new("status", "System health")
            .usage("ops status")
            .handler(|_req, _ctx| {
                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(["ops", "status"]);
assert_eq!(run.exit_code(), 0);

Structs

ActionParam

Metadata for a templated next_action parameter.

AgentCli

Agent-native CLI runtime.

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.

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

Envelope

Unified envelope enum.

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.

truncate_lines_with_file

Truncate lines to max_lines and, when truncated, write full output to a temp file.