Skip to main content
The main crush command launches Crush in interactive mode, providing a terminal-first AI assistant for software development.

​
Usage

crush [flags]

​
Description

Crush is a glamorous, terminal-first AI assistant for software development and adjacent tasks. When you run crush without any subcommands, it launches the interactive TUI (Terminal User Interface) where you can chat with AI models, execute tools, and manage your development workflow.

​
Global Flags

These flags are available for all Crush commands:
​
--cwd
string
default:"current directory"
Current working directory. Use this to run Crush in a specific project directory without changing your shell’s working directory.
​
--data-dir
string
default:"~/.crush"
Custom Crush data directory. Override the default location where Crush stores its configuration, database, and logs.
​
--debug
boolean
default:"false"
Enable debug logging. Shows detailed log output for troubleshooting.
​
--yolo
boolean
default:"false"
Automatically accept all permissions (dangerous mode). Use with caution - this bypasses all permission prompts for tool execution.
​
--help
boolean
default:"false"
Display help information for the command.

​
Configuration Loading

When Crush starts, it loads configuration in the following order:
  1. Project-level config: Looks for crush.json in the current working directory
  2. Global config: Falls back to ~/.crush/crush.json
  3. Context files: Reads project-specific instructions from:
    • AGENTS.md - Instructions for AI agents
    • CRUSH.md - Crush-specific instructions
    • CLAUDE.md - Claude-specific instructions
    • GEMINI.md - Gemini-specific instructions
    • .local variants of any of the above

​
Examples

# Launch Crush in interactive mode
crush

​
Subcommands

Crush provides several subcommands for specific tasks:

​
Initial Setup

On first run, Crush will guide you through:
  1. Provider configuration: Choose and configure an AI provider (Anthropic, OpenAI, Gemini, etc.)
  2. API key setup: Enter your API keys securely
  3. Model selection: Choose your preferred models

​
Data Directory Structure

The Crush data directory (default: ~/.crush) contains: 
.crush/
├── crush.json          # Main configuration file
├── crush.db            # SQLite database for sessions and history
├── logs/
│   └── crush.log      # Application logs
├── stats/
│   └── index.html     # Generated statistics page
└── .gitignore         # Auto-generated to ignore all files

​
Environment Variables

Crush respects the following environment variables:
  • CRUSH_DISABLE_METRICS - Disable telemetry when set to true
  • DO_NOT_TRACK - Disable telemetry when set to true
  • TERM_PROGRAM - Used to detect terminal capabilities
  • WT_SESSION - Used to detect Windows Terminal

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us