Crate argot_cmd 

argot

An agent-first command interface framework for Rust.

argot makes it easy to define structured CLI commands that are equally useful for human operators and AI agents. Every command carries rich metadata — summaries, descriptions, typed arguments, flags, examples, and best-practice guidance — that can be serialized to JSON or rendered as Markdown for consumption by an LLM tool-call layer.

Architecture

The library is built around five cooperating layers:

1. model — the data model: Command, Argument, Flag, Example, and their builders.
2. resolver — maps a raw string token to a Command via exact → prefix → ambiguous resolution.
3. parser — tokenizes a raw argv slice, walks the subcommand tree using the resolver, then binds flags and positional arguments.
4. query — Registry is the central command store; it supports lookup by canonical name, subcommand path, substring search, and fuzzy search.
5. render — three plain-text / Markdown renderers: render_help, render_subcommand_list, and render_markdown.

A convenience cli module provides the Cli struct, which wires all five layers together so you can go from Vec<Command> to a fully functional CLI dispatch loop in a few lines.

Quick Start

use std::sync::Arc;
use argot_cmd::{Command, Flag, Registry, Parser, render_help};

// 1. Build commands.
let cmd = Command::builder("deploy")
    .summary("Deploy the application to an environment")
    .flag(
        Flag::builder("env")
            .description("Target environment")
            .takes_value()
            .required()
            .build()
            .unwrap(),
    )
    .handler(Arc::new(|parsed| {
        println!("deploying to {}", parsed.flags["env"]);
        Ok(())
    }))
    .build()
    .unwrap();

// 2. Store in a registry.
let registry = Registry::new(vec![cmd]);

// 3. Parse raw arguments.
let parser = Parser::new(registry.commands());
let parsed = parser.parse(&["deploy", "--env", "production"]).unwrap();

// 4. Render help.
let help = render_help(parsed.command);
println!("{}", help);

Feature Flags

Feature	Description
derive	Enables the #[derive(ArgotCommand)] proc-macro from argot-cmd-derive.
fuzzy	Enables Registry::fuzzy_search via the fuzzy-matcher crate.
mcp	Enables the MCP stdio transport server (transport).

Modules

• cli — high-level Cli entry point
• model — data model and builders
• resolver — string-to-command resolution
• parser — argv parsing
• query — command registry and search
• render — human-readable and Markdown output

Re-exports

pub use cli::Cli;

pub use cli::CliError;

pub use input_validation::InputValidator;

pub use input_validation::ValidationError;

pub use middleware::Middleware;

pub use model::Argument;

pub use model::ArgumentBuilder;

pub use model::BuildError;

pub use model::Command;

pub use model::CommandBuilder;

pub use model::Example;

pub use model::Flag;

pub use model::FlagBuilder;

pub use model::HandlerFn;

pub use model::ParsedCommand;

pub use model::AsyncHandlerFn;

pub use parser::ParseError;

pub use parser::Parser;

pub use query::command_to_json_with_fields;

pub use query::command_to_ndjson;

pub use query::CommandEntry;

pub use query::QueryError;

pub use query::Registry;

pub use render::render_ambiguity;

pub use render::render_completion;

pub use render::render_docs;

pub use render::render_help;

pub use render::render_json_schema;

pub use render::render_markdown;

pub use render::render_resolve_error;

pub use render::render_skill_file;

pub use render::render_skill_file_with_frontmatter;

pub use render::render_skill_files;

pub use render::render_skill_files_with_frontmatter;

pub use render::render_subcommand_list;

pub use render::DefaultRenderer;

pub use render::Renderer;

pub use render::SkillFrontmatter;

pub use render::Shell;

pub use resolver::ResolveError;

pub use resolver::Resolver;

pub use transport::McpServer;

Modules

cli

High-level CLI entry point that wires together the argot pipeline.

input_validation

Hardened input validation middleware for agent-generated CLI input.

middleware

Middleware hooks for the crate::cli::Cli dispatch loop.

model

Data model for argot commands.

parser

Tokenization and argument parsing for raw argv slices.

query

Central command registry with lookup and search operations.

render

Human-readable and Markdown renderers for commands.

resolver

String-to-command resolution with prefix and ambiguity detection.

transport

MCP (Model Context Protocol) stdio transport server.

Traits

ArgotCommand

Trait implemented by types annotated with #[derive(ArgotCommand)].

Derive Macros

ArgotCommand

Derive macro that implements [argot_cmd::ArgotCommand] for a struct.