Back to Docs / CLI Guide

Dirac CLI User Guide

Dirac CLI is a high-performance, terminal-based AI coding assistant. It is designed to be fast, token-efficient, and highly accurate by using advanced techniques like hash-anchored edits and AST manipulation.

The Living Documentation

Dirac is now self-aware. We ship the minimal functional source code with every release, allowing the agent to answer questions about its own implementation, abilities, and skills in depth. You never have to worry about outdated documentation again.

/askDirac "What would it take to add a new tool?"
Try this in interactive mode

Note: Both the CLI and the VS Code extension share a powerful core backend, ensuring consistent behavior and access to the same advanced toolset across all interfaces.

📦 Installation

Via NPM (Recommended)

Install Dirac globally using npm:

npm install -g dirac-cli

Via Installation Script (macOS/Linux)

Alternatively, use the official installation script:

curl -fsSL https://raw.githubusercontent.com/dirac-run/dirac/master/scripts/install.sh | bash

🔐 Authentication

Before using Dirac, you need to configure an AI provider.

Interactive Setup

Run the following command and follow the prompts to select a provider and enter your API key:

dirac auth

Quick Setup (Non-interactive)

You can also configure a provider directly via flags:

dirac auth --provider anthropic --apikey YOUR_API_KEY --modelid claude-3-5-sonnet-20241022

Environment Variables

Dirac can automatically read API keys from environment variables. This is ideal for CI/CD or persistent terminal configurations.

Provider Environment Variable
Anthropic ANTHROPIC_API_KEY
OpenAI OPENAI_API_KEY
Azure OpenAI AZURE_OPENAI_API_KEY
Google Gemini GEMINI_API_KEY
OpenRouter OPENROUTER_API_KEY
DeepSeek DEEPSEEK_API_KEY
Mistral MISTRAL_API_KEY
Groq GROQ_API_KEY
x.ai (Grok) XAI_API_KEY
HuggingFace HF_TOKEN

Note: When using environment variables for API keys, you must still specify the --provider and --model flags when running a task if they haven't been previously configured via dirac auth.

Custom OpenAI-Compatible Providers

Dirac supports any OpenAI-compatible API, even if it's not explicitly listed. To use a custom provider, set the OPENAI_COMPATIBLE_CUSTOM_KEY environment variable and provide the API's base URL and model name via flags. 

# Example
export OPENAI_COMPATIBLE_CUSTOM_KEY=your_api_key
dirac "Refactor this function" --provider https://api.your-provider.com/v1 --model your-model-name

🚀 Basic Usage

Start a Task

To start a new task, simply run dirac followed by your prompt:

dirac "Refactor the login logic to use JWT"

Interactive Mode

If you run dirac without a prompt, it will open an interactive session where you can chat with the agent. This is also where you can use the /askDirac command to query the agent about its own implementation.

🛠️ Commands

Command Alias Description
task <prompt> t Starts a new task with the given prompt.
history h Lists your task history, allowing you to browse and resume past work.
config Displays your current Dirac configuration and environment status.
auth Opens the authentication and provider configuration menu.
update Checks for Dirac CLI updates and installs them if available.
version Shows the current version of Dirac CLI.
kanban Launches a Kanban board for managing your tasks (requires npx).

⚙️ Options (Flags)

You can customize Dirac's behavior using the following flags:

Execution Modes

  • -p, --plan

    Plan Mode. Dirac will analyze the task and present a detailed strategy before asking for approval to execute.

  • -a, --act

    Act Mode. The default mode where Dirac performs actions and asks for approval.

  • -y, --yolo

    Yolo Mode. Automatically approves all tool actions. Use with caution!

  • --auto-approve-all

    Automatically approves all actions but keeps the interactive UI visible.

Model & Performance

  • -m, --model <model>

    Override the default model for this task.

  • --provider <provider>

    Specify the API provider (requires --model).

  • --thinking [tokens]

    Enable extended thinking for supported models (default: 1024 tokens).

  • --subagents

    Enables the use of subagents for complex, parallelizable tasks.

⌨️ Slash Commands (Interactive Mode)

While in an interactive session, you can use slash commands to control the agent:

/help

Show available commands and usage tips.

/models

Switch the AI model for the current session.

/clear

Clear the current conversation and start fresh.

/newtask

Start a new task while preserving relevant context.

/smol

Manually trigger context condensation to save tokens.

/exit

Exit the interactive session.

/askDirac

Ask Dirac about its own implementation and abilities.

🔗 Piping Context

You can pipe information directly into Dirac from other terminal commands:

git diff | dirac "Review these changes for potential bugs"
cat logs.txt | dirac "Analyze these logs and find the root cause"

Next Guide

VS Code Extension →