Skip to main content

Crush CLI: Comprehensive Quick Start Guide

Welcome to the world of command-line-driven AI development. This guide provides a comprehensive walkthrough of Crush CLI, a powerful tool designed to integrate artificial intelligence directly into your terminal workflow. Whether you're writing code, debugging complex issues, or simply exploring a new codebase, Crush aims to be your indispensable AI partner, boosting your productivity and keeping you in the zone.

1. What is Crush CLI?​

Crush CLI is a sophisticated, terminal-native AI coding assistant. At its core, it's an interactive chat application that lives inside your command line, allowing you to converse with powerful large language models (LLMs) without ever leaving your development environment. Developed by the team at Charm, the creators of many beloved terminal tools, Crush is built with Go, which ensures a snappy, responsive, and resource-efficient experience.

Formerly known as OpenCode, Crush was engineered to solve a specific problem: context-switching. Developers often find themselves toggling between their code editor, their terminal, and a web browser with a chatbot UI. This constant shifting of focus can break concentration and slow down momentum. Crush eliminates this by bringing the AI to you, right where you work.

Who is it for?

Crush is built for any developer, engineer, or student who is comfortable working in a terminal and wants to leverage AI to become more efficient. This includes:

  • Software Developers: Get help writing boilerplate code, generating unit tests, understanding unfamiliar algorithms, or translating code between languages.
  • DevOps Engineers: Draft Dockerfiles, write shell scripts, debug CI/CD pipeline configurations, or ask questions about cloud infrastructure.
  • Data Scientists: Prototype data-parsing scripts, get help with library usage (like Pandas or NumPy), and explore datasets.
  • Students and Learners: Use it as a learning tool to have concepts explained, see code examples, and get instant feedback.

Key Philosophy: Stay in the Flow

The primary advantage of a CLI-based AI tool is the preservation of your "flow state." By remaining in the terminal, you minimize distractions and integrate AI assistance seamlessly into your existing muscle memory and workflows. Crush enhances this by deeply integrating with your project's context, using tools like the Language Server Protocol (LSP) to understand your code on a more fundamental level, leading to more relevant and accurate assistance.

2. Installation and Initial Setup​

Getting Crush up and running is a straightforward process. It's available on a wide range of operating systems and can be installed via several popular package managers.

Supported Platforms:

Crush offers first-class support for:

  • macOS (x86 and ARM)
  • Linux (x86 and ARM)
  • Windows (PowerShell and WSL)
  • FreeBSD, OpenBSD, and NetBSD

Installation Methods:

Choose the method that best suits your operating system and preferences.

  • Homebrew (Recommended for macOS and Linux):

    brew install charmbracelet/tap/crush

    This command taps into Charm's official formula repository and installs the latest version of Crush.

  • NPM (for Node.js users):

    npm install -g @charmland/crush

    The -g flag ensures the package is installed globally, making the crush command available in your system's PATH.

  • Go (for Go developers):

    go install github.com/charmbracelet/crush@latest

    This will download the source code and build the binary, placing it in your Go bin directory ($GOPATH/bin).

  • Arch Linux (via AUR):

    yay -S crush-bin

  • Nix (for NixOS or users of the Nix package manager):

    nix run github:numtide/nix-ai-tools#crush

For other systems, pre-compiled binaries, as well as Debian (.deb) and RPM (.rpm) packages, are available directly from the official GitHub releases page.

Verifying the Installation:

Once installed, you can verify that it's working correctly by running:

crush --version

This should print the installed version number of Crush.

First-Time Setup: Configuring Your AI Provider​

The first time you launch Crush, it will guide you through a simple setup process to connect to an AI provider.

  1. Launch Crush: Open your terminal and run the crush command in your project's root directory.

    crush

  2. Provider Selection: You will be presented with a list of supported AI providers, such as OpenAI, Anthropic, and OpenRouter. Use the arrow keys to highlight your preferred provider and press Enter.

  3. API Key Configuration: Crush will then prompt you to enter an API key for the selected provider.

    • What is an API Key? An API key is a unique secret token that authenticates your requests with the AI provider. You will need to have an account with the provider (e.g., an OpenAI account) to generate one.
    • Paste your key and press Enter. Crush will securely store this key in its configuration for future use.

Alternative: Using Environment Variables

If you prefer to manage your API keys via environment variables (a common best practice), Crush supports this as well. You can set the appropriate variable for your provider in your shell's configuration file (e.g., .zshrc, .bash_profile).

  • For OpenAI: export OPENAI_API_KEY="your-key-here"
  • For Anthropic: export ANTHROPIC_API_KEY="your-key-here"

If these environment variables are set, Crush will use them automatically and skip the manual entry prompt.

3. Core Concepts Explained​

To get the most out of Crush, it's helpful to understand a few of its core concepts.

The Crush Session: Your Conversational Context

Think of a session as a single, continuous conversation about a specific task. When you start Crush, you begin a new session. All the questions you ask and the code you discuss within that session are part of its context. This allows the AI to remember what you've talked about previously, leading to more intelligent and relevant follow-up responses.

The real power comes from multi-session management. A single project can have multiple sessions. For example, you might have one session for developing a new API endpoint (feat-new-endpoint), another for fixing a bug (bug-fix-auth), and a third for general documentation (docs-readme). You can quickly switch between these sessions, and Crush will perfectly preserve the context for each one. This is a major advantage over web-based UIs where you might have dozens of tabs open.

Project Context: How Crush Understands Your Code

Crush isn't just a generic chatbot; it's designed to be deeply aware of your project's structure and content.

  • Initialization: When you run crush in a new project directory, it will ask for permission to initialize the project. This creates a .crush/ directory to store sessions and logs, and a crush.md file that you can use to provide high-level instructions or context about your project.
  • File System Awareness: Crush knows about the files and folders in your project. You can ask it questions like, "Where is the database configuration defined?" and it can search your project to find the answer.
  • Ignoring Files: By default, Crush respects your project's .gitignore file, ensuring that it doesn't read build artifacts, dependency directories (like node_modules), or other ignored files. You can add further patterns to a .crushignore file for more granular control.
  • LSP Integration: For supported languages, Crush can use the Language Server Protocol (LSP) to get a much deeper understanding of your code. This is the same technology that powers features like "Go to Definition" and "Find All References" in modern code editors. It allows Crush to understand classes, functions, and variables, not just as text, but as semantic entities, resulting in far more intelligent assistance.

Multi-Model Support: The Right Tool for the Job

Different LLMs excel at different tasks. One model might be brilliant at writing Python code, while another might be better at creative writing or summarizing technical documentation. Crush embraces this by allowing you to connect to various models from different providers.

Crucially, you can switch models mid-session without losing context. Imagine you're working on a task. You start with a powerful model like GPT-4 to outline a complex feature. Then, you switch to a faster, cheaper model for generating boilerplate code. Crush handles the transition seamlessly, passing the conversation history to the new model so it can pick up right where the other left off.

4. Interactive Usage: A Guided Tour​

Let's walk through a typical workflow to see how you can use Crush in a real-world scenario.

Scenario: You're working on a Python project and need to add a new feature to parse a user profile from a JSON file.

  1. Start a New Session: Navigate to your project's root directory in your terminal and run crush. Let's start a named session for our feature.

    crush -s feat-profile-parser

    This drops you into the Crush interactive UI.

  2. The First Prompt: Generating Code You can start with a natural language prompt.

    You: Write a Python function that takes a file path as input, reads the JSON content, and returns it as a dictionary. Include error handling for file not found and invalid JSON.

    Crush will process this and stream back a response, likely including a complete Python function with comments.

  3. Attaching a File for Context (Ctrl+F) Now, let's say you have an example user.json file. You want the AI to use this file as a reference to create a more specific parser.

    • Press Ctrl+F. A file picker will appear.
    • Navigate to and select user.json.
    • The file is now attached to the chat context.

  4. A Context-Aware Follow-up Prompt:

    You: Great. Now, using the attached JSON file as a template, create a Pydantic model to validate this user structure.

    Because Crush has the context of both the file and your previous request, it can now generate a Pydantic model that precisely matches the structure of your user.json data.

  5. Managing Sessions (Ctrl+P) Suddenly, you get a message about an urgent bug in the authentication system. You don't want to lose your current workflow.

    • Press Ctrl+P. The command palette opens.
    • Select "New Session" and name it bug-auth-fix.
    • You are now in a clean, separate session. You can attach the relevant auth files and work on the bug.
    • Once you're done, press Ctrl+P again, select "Switch Session," and jump right back into feat-profile-parser. Your entire conversation history and file context will be exactly as you left it.

  6. Exploring Commands (Ctrl+P) The command palette is your central hub for actions. Besides managing sessions, you can use it to:

    • Switch the active AI model.
    • Re-run the last prompt.
    • View and manage attached files.
    • Export the chat history.

5. Advanced Configuration and Features​

While Crush works great out of the box, you can customize it further for a more tailored experience.

The crush.json Configuration File

For persistent, project-specific, or global settings, you can use a crush.json file. Crush looks for this file in the following order of precedence:

  1. Project Directory: ./crush.json
  2. Parent Directories: Up to the root /
  3. Global Config Directory:
    • Linux/macOS: ~/.config/crush/crush.json
    • Windows: %USERPROFILE%\AppData\Local\crush\crush.json

Example: Configuring a Local Model with Ollama

One of the most powerful features of Crush is its ability to connect to locally running LLMs via providers like Ollama. This is excellent for privacy, offline work, and cost savings.

Here’s how you would configure it in your crush.json:

{
  "providers": {
    "ollama": {
      "name": "Ollama",
      "base_url": "http://localhost:11434/v1/"
    }
  },
  "model": "ollama/llama3"
}
  • providers: This object defines a new provider named "ollama". We give it a display name and specify the local API endpoint that Ollama exposes.
  • model: This top-level key sets the default model to use. Here, we're telling Crush to use the llama3 model served by our local "ollama" provider.

With this configuration, Crush will direct its requests to your local Ollama instance instead of a cloud provider.

Logging and Debugging

If you ever encounter unexpected behavior or want to see what's happening under the hood, Crush's logging is very helpful.

  • Viewing Logs: The crush logs command lets you inspect the log file, which is stored at .crush/logs/crush.log within your project.

    # Show the last 1000 lines of the log
    crush logs

    # Tail the last 50 lines
    crush logs --tail 50

    # Follow the log file in real-time
    crush logs --follow

  • Debug Mode: For even more verbose output, you can start Crush with the --debug flag or set "debug": true in your crush.json file. This is invaluable for troubleshooting issues with configuration or provider connections.

6. Conclusion​

Crush CLI represents a paradigm shift for developers who want to harness the power of AI without sacrificing their focus or leaving the comfort of the command line. By providing deep project context, multi-session management, and a flexible multi-model architecture, it offers a uniquely powerful and efficient development experience.

This guide has covered the fundamentals to get you started. The best way to learn is to dive in and make it a part of your daily workflow.

For the latest updates, advanced configurations, and to contribute to the project, be sure to visit the official Crush GitHub repository. Happy coding!