sparrow/cli/

mod.rs

use clap::{Parser, Subcommand};
use std::path::PathBuf;

#[derive(Parser)]
#[command(name = "sparrow", about = "one cli · grows with you", version)]
pub struct Cli {
    #[command(subcommand)]
    pub command: Option<Commands>,

    /// Launch terminal TUI (native)
    #[arg(long)]
    pub tui: bool,

    /// Launch webview console (HTTP + WebSocket)
    #[arg(long)]
    pub web: bool,

    /// JSON output (NDJSON event stream)
    #[arg(long)]
    pub json: bool,

    /// Override autonomy level
    #[arg(long)]
    pub autonomy: Option<String>,

    /// Force a specific model
    #[arg(long)]
    pub model: Option<String>,

    /// Prefer local/offline models
    #[arg(long, global = true)]
    pub local: bool,

    /// Session budget cap (USD)
    #[arg(long, global = true)]
    pub budget: Option<f64>,

    /// Hard stop on cumulative USD spent in this run (alias for --budget,
    /// kept separately to match competitor tools' UX).
    #[arg(long, global = true)]
    pub max_cost_usd: Option<f64>,

    /// Hard stop on wall-clock seconds elapsed in this run.
    #[arg(long, global = true)]
    pub max_wall_secs: Option<u64>,

    /// Hard stop on total tokens consumed in this run.
    #[arg(long, global = true)]
    pub max_tokens: Option<u64>,

    /// Bind address for daemon / cockpit servers (default 127.0.0.1).
    /// Use 0.0.0.0 when running under WSL or in a container.
    #[arg(long, global = true)]
    pub bind: Option<String>,

    /// Sandbox backend
    #[arg(long, global = true)]
    pub sandbox: Option<String>,

    /// Profile name
    #[arg(long, global = true)]
    pub profile: Option<String>,

    /// Disable checkpointing
    #[arg(long, global = true)]
    pub no_checkpoint: bool,

    /// Run as a named agent
    #[arg(long)]
    pub agent: Option<String>,

    /// Continue the most recent session (any surface) instead of this
    /// directory's session
    #[arg(long = "continue", global = true)]
    pub continue_last: bool,

    /// Start with a fresh context (ignore this directory's saved session)
    #[arg(long, global = true)]
    pub fresh: bool,

    /// Skip the pre-run quote confirmation
    #[arg(long, global = true)]
    pub yes: bool,
}

#[derive(Subcommand)]
pub enum Commands {
    /// Run a single agentic task
    Run {
        /// Task description
        task: String,

        /// Emit NDJSON event stream (same as the global --json flag, but may
        /// follow the task: `sparrow run "..." --json`)
        #[arg(long)]
        json: bool,
    },

    /// Create a read-only execution plan for a task
    Plan {
        /// Task description
        task: String,

        /// Emit JSON instead of Markdown
        #[arg(long)]
        json: bool,
    },

    /// Interactive multi-turn chat
    Chat,

    /// Launch TUI
    Tui,

    /// Launch first-run setup, then the WebView cockpit
    Launch {
        /// TCP port for the WebView HTTP/WS server
        #[arg(long, default_value = "9339")]
        port: u16,

        /// Launch the terminal TUI instead of the WebView cockpit
        #[arg(long)]
        tui: bool,
    },

    /// Launch webview console (HTTP + WebSocket)
    Console {
        /// TCP port for the webview HTTP/WS server
        #[arg(long, default_value = "9339")]
        port: u16,
    },

    /// Run headless Sparrow runtime daemon
    Daemon,

    /// Manage persistent agents
    Agent {
        #[command(subcommand)]
        action: AgentAction,
    },

    /// Run swarm: planner → coder → verifier
    Swarm {
        /// Task or plan file
        task: String,
    },

    /// Schedule periodic jobs
    Schedule {
        /// Task description
        task: String,

        /// Cron expression
        #[arg(long)]
        cron: String,

        /// Autonomy level for scheduled jobs
        #[arg(long)]
        autonomy: Option<String>,

        /// Report to surfaces
        #[arg(long)]
        report: Vec<String>,
    },

    /// Manage model routing
    Model {
        /// Set active route
        #[arg(long)]
        set: Option<String>,

        /// List available models
        #[arg(long)]
        list: bool,
    },

    /// Configure intelligent auto-routing provider
    Route {
        #[command(subcommand)]
        action: RouteAction,
    },

    /// Manage provider credentials
    Auth {
        #[command(subcommand)]
        action: AuthAction,
    },

    /// Manage skill library
    Skills {
        #[command(subcommand)]
        action: SkillsAction,
    },

    /// Manage local Sparrow plugins
    Plugins {
        #[command(subcommand)]
        action: PluginsAction,
    },

    /// Inspect and gate toolsets
    Tools {
        #[command(subcommand)]
        action: ToolsAction,
    },

    /// Security audit of config, permissions, plugins, hooks, secrets
    Security {
        #[command(subcommand)]
        action: SecurityAction,
    },

    /// GitHub Action / remote PR workflow
    Github {
        #[command(subcommand)]
        action: GithubAction,
    },

    /// Compact context and write a durable handoff doc
    Compact {
        /// Task description (recorded in the handoff)
        #[arg(long)]
        task: Option<String>,
        /// Output path (default: .sparrow/handoff/<timestamp>.md)
        #[arg(long)]
        out: Option<PathBuf>,
        /// Emit JSON instead of Markdown to stdout (the file is always Markdown)
        #[arg(long)]
        json: bool,
    },

    /// Manage MCP connectors
    Mcp {
        #[command(subcommand)]
        action: McpAction,
    },

    /// List checkpoints
    Checkpoint {
        #[command(subcommand)]
        action: CheckpointAction,
    },

    /// Rewind to a checkpoint
    Rewind {
        /// Checkpoint ID or number
        id: String,
    },

    /// Replay a transcript
    Replay {
        /// Run ID to replay
        run_id: String,
        /// Open an interactive TUI scrubber (←/→ to step through events)
        #[arg(long)]
        scrub: bool,
    },

    /// Start/stop gateway daemon
    Gateway {
        #[command(subcommand)]
        action: GatewayAction,
    },

    /// Manage saved sessions
    Sessions {
        #[command(subcommand)]
        action: SessionAction,
    },

    /// Interactive tutorial
    Learn,

    /// Initialize a project with .sparrow/ config
    Init,

    /// Show live status (active runs, budget, session)
    Status,

    /// Manage persistent memory
    Memory {
        #[command(subcommand)]
        action: MemoryAction,
    },

    /// Inspect and update permission policy
    Permissions {
        #[command(subcommand)]
        action: PermissionAction,
    },

    /// Profile management
    Profile {
        #[command(subcommand)]
        action: ProfileAction,
    },

    /// Import config from another tool (claude-code, codex, opencode, openclaw)
    Import {
        #[command(subcommand)]
        source: ImportSource,
    },

    /// Edit configuration
    Config {
        /// Open config.toml in editor
        #[arg(short)]
        edit: bool,
    },

    /// Self-update
    Update,

    /// Run diagnostics
    Doctor,

    /// (Re)run conversational setup
    Setup,

    /// Run a self-contained demo (snake game)
    Demo,

    /// Share latest session as GitHub Gist
    Share,

    /// Install or scan security pre-commit hooks
    Hook {
        #[command(subcommand)]
        action: HookAction,
    },

    /// Voice commands (speak, transcribe, providers)
    Voice {
        #[command(subcommand)]
        action: VoiceAction,
    },

    /// Test browser/vision (screenshot, navigate)
    Browser {
        /// URL to test
        #[arg(default_value = "https://example.com")]
        url: String,
    },
}

#[derive(Subcommand)]
pub enum AgentAction {
    Create { name: String },
    List,
    Edit { name: String },
    Rm { name: String },
    Run { name: String, task: String },
    Mention { name: String, message: String },
}

#[derive(Subcommand)]
pub enum AuthAction {
    Add {
        provider: String,
    },
    List,
    Rm {
        provider: String,
    },
    /// Authenticate a provider via OAuth device flow (github/google/microsoft).
    Login {
        provider: String,
        /// OAuth client id (or set <PROVIDER>_CLIENT_ID env var)
        #[arg(long)]
        client_id: Option<String>,
    },
}

#[derive(Subcommand)]
pub enum SkillsAction {
    List,
    View {
        name: String,
    },
    Create {
        name: String,
    },
    /// Install a skill from GitHub (gh:user/repo[/path]), a git URL, or a
    /// local path to a SKILL.md
    Install {
        source: String,
    },
    Update {
        name: String,
    },
    Prune,
    /// Remove a skill by name (e.g. to delete junk auto-learned skills)
    Rm {
        name: String,
    },
}

#[derive(Subcommand)]
pub enum PluginsAction {
    List,
    Install {
        source: String,
        #[arg(long)]
        allow: bool,
    },
    Rm {
        name: String,
    },
}

#[derive(Subcommand)]
pub enum GithubAction {
    /// Review a pull request: fetch diff via `gh`, run a read-only review prompt
    Review {
        /// PR number
        pr: u64,
        /// Print the review plan without invoking the model or posting comments
        #[arg(long)]
        dry_run: bool,
        /// Override the model id
        #[arg(long)]
        model: Option<String>,
        /// Restrict tool allow-list (comma-separated). Empty = inherit config.
        #[arg(long)]
        allowed_tools: Option<String>,
    },
    /// Show CI status for the current branch (via `gh run list`)
    Status,
    /// Fetch CI logs for a workflow run id (via `gh run view --log`)
    Logs { run_id: String },
}

#[derive(Subcommand)]
pub enum SecurityAction {
    /// Run a full security audit
    Audit {
        /// Emit JSON instead of human-readable summary
        #[arg(long)]
        json: bool,
    },
}

#[derive(Subcommand)]
pub enum ToolsAction {
    List {
        #[arg(long)]
        surface: Option<String>,
    },
    Enable {
        tool: String,
    },
    Disable {
        tool: String,
    },
}

#[derive(Subcommand)]
pub enum McpAction {
    Add {
        server: String,

        /// Command to launch the MCP server
        #[arg(long)]
        command: Option<String>,

        /// Command arguments, either repeated or space-delimited
        #[arg(long, value_delimiter = ' ', allow_hyphen_values = true)]
        args: Vec<String>,

        /// Transport backend: stdio, sse, or url
        #[arg(long)]
        transport: Option<String>,
    },
    List,
    Rm {
        server: String,
    },
}

#[derive(Subcommand)]
pub enum CheckpointAction {
    /// List all checkpoints
    List,
    /// Show diff between HEAD and a checkpoint
    Diff {
        /// Checkpoint ID
        id: String,
    },
    /// Delete checkpoints older than N days (default: 30)
    Prune {
        /// Remove checkpoints older than this many days
        #[arg(long, default_value = "30")]
        older_than_days: u64,
    },
}

#[derive(Subcommand)]
pub enum GatewayAction {
    Start,
    Status,
    Health,
    Abort { run: String },
    Stop,
}

#[derive(Subcommand)]
pub enum SessionAction {
    List,
    Export {
        id: String,
        path: Option<PathBuf>,
    },
    Cleanup {
        #[arg(long, default_value_t = 30)]
        older_than_days: u64,
    },
    /// Full-text search across sessions
    Search {
        query: String,
        #[arg(long, default_value_t = 10)]
        limit: usize,
    },
}

#[derive(Subcommand)]
pub enum ProfileAction {
    Create { name: String },
    List,
    Use { name: String },
}

#[derive(Subcommand)]
pub enum ImportSource {
    /// Import from Claude Code (~/.claude/)
    ClaudeCode {
        /// Path to project with .claude/ directory (defaults to cwd)
        path: Option<PathBuf>,
    },
    /// Import from OpenAI Codex CLI (~/.codex/)
    Codex {
        /// Path to project with codex config (defaults to cwd)
        path: Option<PathBuf>,
    },
    /// Import from OpenCode (~/.config/opencode/)
    #[command(name = "opencode")]
    OpenCode {
        /// Path to project with opencode.json (defaults to cwd)
        path: Option<PathBuf>,
    },
    /// Import from OpenClaw (~/.openclaw/)
    Openclaw {
        /// Path to the OpenClaw config directory (defaults to ~/.openclaw)
        path: Option<PathBuf>,
    },
    /// Auto-detect installed tools and import each one
    Auto,
}

#[derive(Subcommand)]
pub enum MemoryAction {
    List,
    Forget {
        id: String,
    },
    Add {
        key: String,
        value: String,
    },
    Replace {
        id: String,
        key: String,
        value: String,
    },
    Recall {
        query: String,
        #[arg(long, default_value_t = 10)]
        limit: usize,
    },
    Consolidate,
    Docs,
    Search {
        query: String,
        #[arg(long, default_value_t = 10)]
        limit: usize,
    },
    Scroll {
        session: String,
        #[arg(long, default_value_t = 0)]
        around: usize,
        #[arg(long, default_value_t = 3)]
        before: usize,
        #[arg(long, default_value_t = 3)]
        after: usize,
    },
    Graph {
        #[command(subcommand)]
        action: GraphAction,
    },
}

#[derive(Subcommand)]
pub enum GraphAction {
    UpsertNode {
        id: String,
        label: String,
        #[arg(long, default_value = "entity")]
        kind: String,
        #[arg(long, default_value = "{}")]
        properties: String,
    },
    UpsertEdge {
        from_id: String,
        relation: String,
        to_id: String,
        #[arg(long)]
        id: Option<String>,
        #[arg(long, default_value_t = 1.0)]
        weight: f64,
        #[arg(long, default_value = "{}")]
        properties: String,
    },
    Get {
        id: String,
    },
    Neighbors {
        id: String,
        #[arg(long, default_value = "both")]
        direction: String,
        #[arg(long, default_value_t = 20)]
        limit: usize,
    },
    Search {
        query: String,
        #[arg(long, default_value_t = 20)]
        limit: usize,
    },
    Export,
    DeleteNode {
        id: String,
    },
    DeleteEdge {
        id: String,
    },
    SyncNeo4j,
}

#[derive(Subcommand)]
pub enum PermissionAction {
    /// Show current permission mode and rules
    List,
    /// Set permission mode (read-only|plan|supervised|trusted|autonomous|emergency-stop)
    Set { mode: String },
    /// Add an explicitly allowed tool pattern
    AllowTool { tool: String },
    /// Add a tool pattern that always asks for approval
    AskTool { tool: String },
    /// Add an explicitly denied tool pattern
    DenyTool { tool: String },
    /// Add an allowed path boundary
    AllowPath { path: PathBuf },
    /// Add a denied path boundary
    DenyPath { path: PathBuf },
}

#[derive(Subcommand)]
pub enum RouteAction {
    /// Pin the intelligent auto-router to a specific provider for all tiers.
    /// Example: sparrow route set opencode-go
    Set {
        /// Provider ID to use for all task tiers (e.g. opencode-go, anthropic, nvidia)
        provider: String,
    },
    /// Clear the pinned provider — let the multi-tier policy decide per task.
    Clear,
    /// Show the current routing config (preferred provider + per-tier policy).
    Show,
}

#[derive(Subcommand)]
pub enum HookAction {
    /// Install pre-commit security hook
    Install,
    /// Scan staged files (or all files with --all) for secrets
    Scan {
        /// Scan entire working tree instead of just staged files
        #[arg(long)]
        all: bool,
    },
}

#[derive(Subcommand)]
pub enum VoiceAction {
    /// Convert text to speech
    Speak { text: String },
    /// Transcribe audio file
    Transcribe { file: String },
    /// List available voice providers
    Providers,
}