CLI command reference¶

usage: keprix [-h] [--version] [-z PROMPT] [-m MODEL] [--provider PROVIDER]
              [-t TOOLSETS] [--resume SESSION] [--continue [SESSION_NAME]]
              [--worktree] [--accept-hooks] [--skills SKILLS] [--yolo]
              [--pass-session-id] [--ignore-user-config] [--ignore-rules]
              [--safe-mode] [--tui] [--cli] [--dev]
              {chat,model,fallback,secrets,migrate,gateway,proxy,lsp,setup,postinstall,whatsapp,whatsapp-cloud,slack,send,login,logout,auth,status,cron,webhook,portal,kanban,hooks,doctor,readiness,configure,health,proposals,approve,reject,repair,rollback,sdk,slash,coding,opportunity,mutation,research,builder,ingest,crm-ingest,crm-migrate,crm-funnel,document-vault,outreach-scheduler,agent-os,vault,upgrade,integrations,upstream,scout,channel-shield,email-shield,product,sidecar,ops,incident,forensics,audit,policy,language,agent-app,security,dump,debug,backup,usage,checkpoints,import,config,pairing,skills,bundles,plugins,curator,memory,tools,computer-use,mcp,sessions,insights,claw,version,update,uninstall,acp,profile,completion,dashboard,desktop,gui,logs,prompt-size}
              ...

Keprix - AI assistant with tool-calling capabilities

positional arguments:
  {chat,model,fallback,secrets,migrate,gateway,proxy,lsp,setup,postinstall,whatsapp,whatsapp-cloud,slack,send,login,logout,auth,status,cron,webhook,portal,kanban,hooks,doctor,readiness,configure,health,proposals,approve,reject,repair,rollback,sdk,slash,coding,opportunity,mutation,research,builder,ingest,crm-ingest,crm-migrate,crm-funnel,document-vault,outreach-scheduler,agent-os,vault,upgrade,integrations,upstream,scout,channel-shield,email-shield,product,sidecar,ops,incident,forensics,audit,policy,language,agent-app,security,dump,debug,backup,usage,checkpoints,import,config,pairing,skills,bundles,plugins,curator,memory,tools,computer-use,mcp,sessions,insights,claw,version,update,uninstall,acp,profile,completion,dashboard,desktop,gui,logs,prompt-size}
                        Command to run
    chat                Interactive chat with the agent
    model               Select default model and provider
    fallback            Manage fallback providers (tried when the primary
                        model fails)
    secrets             Manage external secret sources (Bitwarden Secrets
                        Manager)
    migrate             Migrate configuration for retired models or deprecated
                        settings
    gateway             Messaging gateway management
    proxy               Credential injection proxy and OAuth upstream proxy
    lsp                 Language Server Protocol management
    setup               Interactive setup wizard
    postinstall         Bootstrap non-Python deps for pip installs (node,
                        browser, ripgrep, ffmpeg)
    whatsapp            Set up WhatsApp integration
    whatsapp-cloud      Set up WhatsApp Business Cloud API integration
    slack               Slack integration helpers (manifest generation, etc.)
    send                Send a message to a configured platform (scripts, cron
                        jobs, CI).
    login               Authenticate with an inference provider
    logout              Clear authentication for an inference provider
    auth                Manage pooled provider credentials
    status              Show status of all components
    cron                Cron job management
    webhook             Manage dynamic webhook subscriptions
    portal              Set up Nous Portal (login, model pick, Tool Gateway);
                        see also `portal info`
    kanban              Multi-profile collaboration board (tasks, links,
                        comments)
    hooks               Inspect and manage shell-script hooks
    doctor              Check configuration and dependencies
    readiness           Market, upgrade, and recovery readiness report
    configure           Run environment discovery (first-run wizard)
    health              Show current component health status
    proposals           List pending config optimization proposals
    approve             Apply a config proposal after review
    reject              Dismiss a config proposal
    repair              Manually trigger auto-repair for all components
    rollback            Roll back a specific env var to its previous value
    sdk                 Manage App Foundation SDK registrations
    slash               List and run slash commands
    coding              SWE-agent-style issue-to-patch runner
    opportunity         Opportunity Engine: discover and validate market
                        opportunities
    mutation            Manage synthesized tools and mutation queue
    research            Research workspace projects and YAML playbooks
    builder             Project builder and monorepo manager
    ingest              Ingest external media and artifacts
    crm-ingest          Canonical CRM lead spreadsheet import/export
    crm-migrate         Migrate CRM/outreach SQLite into Postgres (dry-run or
                        apply)
    crm-funnel          CRM funnel orchestrator, next-best-action, and channel
                        journey
    document-vault      Document Vault inventory, flags, and adapter registry
    outreach-scheduler  Durable outreach campaign sequence scheduler (claim-
                        lease ticks)
    agent-os            Agent OS utilities
    vault               Initialize and validate local markdown vaults
    upgrade             Safe, guided Keprix upgrades for products (check,
                        plan, dry-run, execute)
    integrations        Manage optional integrations
    upstream            Monitor Hermes upstream releases and manage feature
                        adoption
    scout               Scout connectivity and integration tests
    channel-shield      Channel Shield doctor, adapters, and fixture E2E
    email-shield        Alias for channel-shield (email-focused)
    product             Product sidecar provision, registry, Scout register,
                        and conformance
    sidecar             Keprix Universal Sidecar: manifest, pair, invoke,
                        jobs, conformance
    ops                 Security operations runbook and reports
    incident            Incident response commands
    forensics           Forensic snapshot and chain-of-custody tools
    audit               Audit chain verification
    policy              Show or set operator-owned policy profiles
    language            Detect, translate, and transcribe text
    agent-app           Portable agent apps: validate, run, eval, and bundle
    security            Supply-chain audit (OSV.dev) for venv, plugins, and
                        MCP servers
    dump                Dump setup summary for support/debugging
    debug               Debug tools; upload logs and system info for support
    backup              Back up Keprix home directory to a zip file
    usage               LLM token usage and cost analytics
    checkpoints         Inspect / prune / clear ~/.keprix/checkpoints/
    import              Restore a Keprix backup from a zip file
    config              View and edit configuration
    pairing             Manage DM pairing codes for user authorization
    skills              Search, install, configure, and manage skills
    bundles             Create, list, and manage skill bundles (aliases for
                        multiple skills)
    plugins             Manage plugins; install, update, remove, list
    curator             Background skill maintenance (curator); status, run,
                        pause, pin
    memory              Configure external memory provider
    tools               Configure which tools are enabled per platform
    computer-use        Manage the Computer Use (cua-driver) backend (macOS)
    mcp                 Manage MCP servers and run Keprix as an MCP server
    sessions            Manage session history (list, rename, export, prune,
                        delete)
    insights            Show usage insights and analytics
    claw                OpenClaw migration tools
    version             Show version information
    update              Update Keprix to the latest version
    uninstall           Uninstall Keprix
    acp                 Run Keprix as an ACP (Agent Client Protocol) server
    profile             Manage profiles; multiple isolated Keprix instances
    completion          Print shell completion script (bash, zsh, or fish)
    dashboard           Start the web UI dashboard
    desktop (gui)       Build and launch the native desktop app
    logs                View and filter Keprix log files
    prompt-size         Show a byte breakdown of the system prompt + tool
                        schemas

options:
  -h, --help            show this help message and exit
  --version, -V         Show version and exit
  -z PROMPT, --oneshot PROMPT
                        One-shot mode: send a single prompt and print ONLY the
                        final response text to stdout. No banner, no spinner,
                        no tool previews, no session_id line. Tools, memory,
                        rules, and AGENTS.md in the CWD are loaded as normal;
                        approvals are auto-bypassed. Intended for scripts /
                        pipes.
  -m MODEL, --model MODEL
                        Model override for this invocation (e.g.
                        anthropic/claude-sonnet-4.6). Applies to -z/--oneshot
                        and --tui. Also settable via KEPRIX_INFERENCE_MODEL
                        env var.
  --provider PROVIDER   Provider override for this invocation (e.g.
                        openrouter, anthropic). Applies to -z/--oneshot and
                        --tui. The persistent provider lives in config.yaml
                        under model.provider; use `keprix setup` or edit the
                        file to change it.
  -t TOOLSETS, --toolsets TOOLSETS
                        Comma-separated toolsets to enable for this
                        invocation. Applies to -z/--oneshot and --tui.
  --resume SESSION, -r SESSION
                        Resume a previous session by ID or title
  --continue [SESSION_NAME], -c [SESSION_NAME]
                        Resume a session by name, or the most recent if no
                        name given
  --worktree, -w        Run in an isolated git worktree (for parallel agents)
  --accept-hooks        Auto-approve any unseen shell hooks declared in
                        config.yaml without a TTY prompt. Equivalent to
                        KEPRIX_ACCEPT_HOOKS=1 or hooks_auto_accept: true in
                        config.yaml. Use on CI / headless runs that can't
                        prompt.
  --skills SKILLS, -s SKILLS
                        Preload one or more skills for the session (repeat
                        flag or comma-separate)
  --yolo                Bypass all dangerous command approval prompts (use at
                        your own risk)
  --pass-session-id     Include the session ID in the agent's system prompt
  --ignore-user-config  Ignore ~/.keprix/config.yaml and fall back to built-in
                        defaults (credentials in .env are still loaded)
  --ignore-rules        Skip auto-injection of AGENTS.md, SOUL.md,
                        .cursorrules, memory, and preloaded skills
  --safe-mode           Troubleshooting mode: disable ALL customizations;
                        user config, AGENTS.md/memory injection, plugins, and
                        MCP servers (implies --ignore-user-config and
                        --ignore-rules)
  --tui                 Launch the modern TUI instead of the classic REPL
  --cli                 Force the classic prompt_toolkit REPL (overrides
                        display.interface=tui)
  --dev                 With --tui: run TypeScript sources via tsx (skip dist
                        build)

Examples:
    keprix                        Start interactive chat
    keprix chat -q "Hello"        Single query mode
    keprix --tui                  Launch the modern TUI (or set display.interface: tui)
    keprix --cli                  Force the classic REPL (overrides display.interface: tui)
    keprix -c                     Resume the most recent session
    keprix -c "my project"        Resume a session by name (latest in lineage)
    keprix --resume <session_id> Resume a specific session by ID
    keprix setup                  Run setup wizard
    keprix logout                 Clear stored authentication
    keprix auth add <provider> Add a pooled credential
    keprix auth list              List pooled credentials
    keprix auth remove <p> <t> Remove pooled credential by index, id, or label
    keprix auth reset <provider> Clear exhaustion status for a provider
    keprix model                  Select default model
    keprix fallback [list]        Show fallback provider chain
    keprix fallback add           Add a fallback provider (same picker as `keprix model`)
    keprix fallback remove        Remove a fallback provider from the chain
    keprix config                 View configuration
    keprix config edit            Edit config in $EDITOR
    keprix config set model gpt-4 Set a config value
    keprix gateway                Run messaging gateway
    keprix -s keprix-dev,github-auth
    keprix -w                     Start in isolated git worktree
    keprix gateway install        Install gateway background service
    keprix sessions list          List past sessions
    keprix sessions browse        Interactive session picker
    keprix sessions rename ID T   Rename/title a session
    keprix logs                   View agent.log (last 50 lines)
    keprix logs -f                Follow agent.log in real time
    keprix logs errors            View errors.log
    keprix logs --since 1h        Lines from the last hour
    keprix debug share             Upload debug report for support
    keprix update                 Update to latest version
    keprix dashboard              Start web UI dashboard (port 9119)
    keprix dashboard --stop       Stop running dashboard processes
    keprix dashboard --status     List running dashboard processes

For more help on a command:
    keprix <command> --help