pub mod agent_args;
pub mod destructive;
pub mod overrides;
use std::path::PathBuf;
use clap::{Parser, Subcommand, ValueEnum};
pub use agent_args::AgentArgs;
use crate::config::{DEFAULT_PER_PAGE, DEFAULT_SEARCH_LIMIT};
#[derive(Debug, Clone, Parser)]
#[command(
name = "docsrs-cli",
version,
about = "One-shot CLI for crates.io and docs.rs documentation",
long_about = "One-shot BORN→EXECUTE→DIE CLI for crates.io and docs.rs.
\
Stdout is the data contract (JSON or markdown). Stderr is diagnostics only.
\
JSON is automatic when stdout is not a TTY; force human with --format markdown|text.
\
First Ctrl-C / SIGINT cancels cooperatively (exit 130). Second Ctrl-C within 5s force-exits 130.
\
SIGTERM and SIGHUP cancel as terminate (exit 143). On Windows, Ctrl+Break and console close also terminate (143).
\
Broken pipe on stdout is exit 141 (pipeline-safe; no stack trace).",
after_help = "Examples:
\
docsrs-cli search-crates serde --json
\
docsrs-cli readme tokio --json
\
docsrs-cli get-item clap trait clap::Parser --json
\
docsrs-cli search-in-crate reqwest Client --json
\
docsrs-cli doctor --json
\
docsrs-cli config path --json
\
docsrs-cli config show --json
\
docsrs-cli config init --json
\
docsrs-cli commands --json
\
docsrs-cli completions bash
\
docsrs-cli --dry-run readme serde
\
# Agents: JSON is auto when stdout is not a TTY; force markdown with --format markdown",
disable_help_subcommand = false
)]
pub struct Cli {
#[arg(long, global = true)]
pub json: bool,
#[arg(long, global = true, value_enum)]
pub format: Option<OutputFormat>,
#[arg(long, global = true)]
pub timeout: Option<u64>,
#[arg(long, global = true)]
pub connect_timeout: Option<u64>,
#[arg(long, global = true)]
pub user_agent: Option<String>,
#[arg(long, global = true)]
pub lang: Option<String>,
#[arg(long, global = true)]
pub config_dir: Option<PathBuf>,
#[arg(long, global = true)]
pub cache_dir: Option<PathBuf>,
#[arg(long, global = true)]
pub no_cache: bool,
#[arg(long, global = true)]
pub cache_ttl_secs: Option<u64>,
#[arg(long, global = true)]
pub max_cache_bytes: Option<u64>,
#[arg(long, global = true)]
pub dry_run: bool,
#[arg(long, global = true)]
pub max_body_bytes: Option<u64>,
#[command(flatten)]
pub agent: AgentArgs,
#[arg(long, global = true)]
pub rate_limit_delay_ms: Option<u64>,
#[arg(long, global = true)]
pub max_concurrency: Option<u32>,
#[arg(long, global = true)]
pub max_retries: Option<u32>,
#[arg(long, global = true)]
pub retry_base_ms: Option<u64>,
#[arg(long, global = true)]
pub retry_max_delay_ms: Option<u64>,
#[arg(long, global = true)]
pub retry_max_elapsed_ms: Option<u64>,
#[arg(long, global = true)]
pub disable_retry: bool,
#[arg(long, global = true)]
pub allow_loopback: bool,
#[arg(short = 'v', long, global = true, action = clap::ArgAction::Count)]
pub verbose: u8,
#[arg(short = 'q', long, global = true)]
pub quiet: bool,
#[arg(long, global = true)]
pub no_color: bool,
#[command(subcommand)]
pub command: Commands,
}
#[derive(Debug, Clone, Copy, ValueEnum, PartialEq, Eq)]
pub enum OutputFormat {
Markdown,
Json,
Text,
}
#[derive(Debug, Clone, Subcommand)]
pub enum Commands {
SearchCrates {
#[arg(default_value = "")]
query: String,
#[arg(long, default_value_t = DEFAULT_PER_PAGE)]
per_page: u32,
#[arg(long, value_enum, default_value_t = SortKind::Relevance)]
sort: SortKind,
#[arg(long, default_value_t = 1, conflicts_with = "page_token")]
page: u32,
#[arg(long, conflicts_with = "page")]
page_token: Option<String>,
},
Readme {
crate_name: String,
#[arg(long)]
crate_version: Option<String>,
},
GetItem {
crate_name: String,
item_type: String,
item_path: String,
#[arg(long)]
crate_version: Option<String>,
#[arg(long)]
suggest: bool,
},
SearchInCrate {
crate_name: String,
#[arg(default_value = "")]
query: String,
#[arg(long)]
crate_version: Option<String>,
#[arg(long)]
item_type: Option<String>,
#[arg(long, default_value_t = DEFAULT_SEARCH_LIMIT)]
limit: u32,
#[arg(long, default_value = "prefix")]
r#match: String,
},
Version,
Doctor {
#[arg(long)]
online: bool,
},
Commands,
Schema {
#[arg(long)]
cmd: String,
},
Completions {
#[arg(value_enum)]
shell: Shell,
},
Cache {
#[command(subcommand)]
action: CacheAction,
},
Config {
#[command(subcommand)]
action: ConfigAction,
},
}
#[derive(Debug, Clone, Subcommand)]
pub enum CacheAction {
Path,
Clear {
#[arg(long)]
yes: bool,
},
Stats,
}
#[derive(Debug, Clone, Subcommand)]
pub enum ConfigAction {
Path,
Show,
Init {
#[arg(long)]
force: bool,
#[arg(long)]
yes: bool,
},
}
#[derive(Debug, Clone, Copy, ValueEnum, PartialEq, Eq)]
pub enum SortKind {
Relevance,
Downloads,
#[value(name = "recent-downloads")]
RecentDownloads,
#[value(name = "recent-updates")]
RecentUpdates,
New,
Alphabetical,
}
impl SortKind {
pub fn as_api_str(self) -> &'static str {
match self {
Self::Relevance => "relevance",
Self::Downloads => "downloads",
Self::RecentDownloads => "recent-downloads",
Self::RecentUpdates => "recent-updates",
Self::New => "new",
Self::Alphabetical => "alphabetical",
}
}
}
#[derive(Debug, Clone, Copy, ValueEnum)]
pub enum Shell {
Bash,
Zsh,
Fish,
Elvish,
#[value(name = "power-shell", alias = "powershell")]
PowerShell,
}
impl Shell {
pub fn as_str(self) -> &'static str {
match self {
Self::Bash => "bash",
Self::Zsh => "zsh",
Self::Fish => "fish",
Self::Elvish => "elvish",
Self::PowerShell => "power-shell",
}
}
pub fn to_clap_shell(self) -> clap_complete::Shell {
match self {
Self::Bash => clap_complete::Shell::Bash,
Self::Zsh => clap_complete::Shell::Zsh,
Self::Fish => clap_complete::Shell::Fish,
Self::Elvish => clap_complete::Shell::Elvish,
Self::PowerShell => clap_complete::Shell::PowerShell,
}
}
}
impl Commands {
pub fn wire_name(&self) -> &'static str {
match self {
Self::SearchCrates { .. } => "search-crates",
Self::Readme { .. } => "readme",
Self::GetItem { .. } => "get-item",
Self::SearchInCrate { .. } => "search-in-crate",
Self::Version => "version",
Self::Doctor { .. } => "doctor",
Self::Commands => "commands",
Self::Schema { .. } => "schema",
Self::Completions { .. } => "completions",
Self::Cache { action } => match action {
CacheAction::Path => "cache-path",
CacheAction::Clear { .. } => "cache-clear",
CacheAction::Stats => "cache-stats",
},
Self::Config { action } => match action {
ConfigAction::Path => "config-path",
ConfigAction::Show => "config-show",
ConfigAction::Init { .. } => "config-init",
},
}
}
}
impl Cli {
pub fn wire_command(&self) -> &'static str {
self.command.wire_name()
}
pub fn wants_json(&self, stdout_is_terminal: bool) -> bool {
if self.json || matches!(self.format, Some(OutputFormat::Json)) {
return true;
}
if matches!(
self.format,
Some(OutputFormat::Markdown | OutputFormat::Text)
) {
return false;
}
!stdout_is_terminal
}
pub fn validate_format_conflict(&self) -> Result<(), crate::error::AppError> {
use crate::error::{AppError, ErrorDetail};
if self.json
&& matches!(
self.format,
Some(OutputFormat::Text | OutputFormat::Markdown)
)
{
return Err(AppError::of(ErrorDetail::JsonFormatConflict));
}
Ok(())
}
}
#[cfg(test)]
mod tests;