Reference

Commands

Every RaggieCode command at your fingertips. CLI commands for running the agent and managing configuration, in-chat commands for controlling sessions, and the five effort levels that govern subagent depth.

Estimated read time: 7 minutes · Updated July 12, 2026

CLI Commands

RaggieCode provides five CLI commands that you run directly from your terminal. Each one is available after installation via pip install.

`raggie code`

Run the AI agent with a specific role in a project directory. This is the main command you will use every day.

Argument	Required	Description
`role`	Yes	Agent role defined in `roles.json`. Default: `"code"`
`project-dir`	No	Path to project directory. Use `.` for current dir. Created if it doesn't exist. Default: `.`
`--prompt`	No	Single prompt for headless execution. Omit for interactive chat mode.
`--effort`	No	Effort level 1-5 (zen, serious, extreme, feral, insane). Controls max subagent depth.
`--debug`	No	Show raw tool call outputs for debugging.

Examples:

Terminal

raggie code /path/to/project --prompt "Refactor the API router to use dependency injection"
raggie code /path/to/project
raggie code . --debug
raggie code myproject --effort 5

`raggie setup`

First-time setup wizard. Guides you through configuring API keys and reviewing agent roles .; everything you need to get started. The wizard creates ~/.config/raggie/keys.json and ~/.config/raggie/roles.json.

                  
                  
                  
                  raggie setup
                

                  $ raggie setup

  Raggie Setup Wizard
============================================================

  Step 1: Configure your API keys.
  You'll need at least one API key to use Raggie.

  API Keys
  ----------------------------------------
    1. https://api.deepseek.com -> sk-e***************************ed71
    2. https://openrouter.ai/api/v1 -> sk-o**************************58cf

  q. Skip
  1. Add key
  2. Remove key

  Choice: q

  Step 2: Review your agent roles.
  Roles define which model and base URL each agent uses.

  Agent Roles
  ------------------------------------------------------------
    1. code
       Model:          deepseek-v4-flash
       Base URL:       https://api.deepseek.com
       Context Window: 500000
       Prompt:         coder_system_prompt.md
       Reasoning:      off
       Streaming:      off

  q. Exit
  1. Edit role's base URL / model

  Choice: q

============================================================
    Setup complete! You're ready to use Raggie.
    Try: raggie code .
============================================================
                

`raggie keys`

Manage API keys via an interactive menu. Keys are stored in ~/.config/raggie/keys.json. Options: Add key, Remove key, Exit (press q).

Terminal

raggie keys

`raggie roles`

List and edit agent roles via an interactive menu. Roles are stored in ~/.config/raggie/roles.json. Options: Edit role's base URL / model, Exit (press q).

Terminal

raggie roles

`raggie skill`

Manage named skills stored in the database. A role can have multiple skills, each identified by a unique name. Running raggie skill or raggie skill <role> without flags opens an interactive menu.

                  
                  
                  
                  raggie skill code
                

                  $ raggie skill code

Skills for role 'code'
------------------------------------------------------------
  1. testing: Always write tests after implementing. Use pytest.
  2. refactoring: When refactoring, preserve behavior.
------------------------------------------------------------
q. Exit
1. View skill content
2. Delete skill
3. Export skill to file
4. Import skill from file
5. List all skills (all roles)
                

CLI flags for scripting:

Flag	Description
`--show`	Display all skills for the role (or a specific skill with `--name`)
`--name <name>`	Specify the skill name (required for import/export/delete)
`--import-skill <file>`	Import a skill from a Markdown file into the database (requires `--name`)
`--export-skill <file>`	Export a skill from the database to a Markdown file (requires `--name`)
`--delete`	Delete a skill (requires `--name`)
`--list-all`	List all skills across all roles (role arg not required)

Examples:

Terminal

raggie skill code                          # interactive menu for role 'code'
raggie skill                               # interactive menu (all roles)
raggie skill code --show --name testing     # show full content of a specific skill
raggie skill code --import-skill my-skills.md --name testing   # import from file
raggie skill code --export-skill backup.md --name testing      # export to file
raggie skill code --delete --name testing   # delete a skill
raggie skill --list-all                    # list all skills across all roles

In-Chat Commands

These commands are available inside the interactive chat loop. They are intercepted before reaching the LLM and handled locally .; no tokens are consumed for them.

Command	Description
`/undo`	Undo the last agent commit (restore previous file state)
`/redo`	Re-apply the last undone commit
`/streaming on\|off`	Toggle streaming mode mid-conversation. Persists to `roles.json`
`/reasoning on\|off`	Toggle reasoning output mid-conversation. Persists to `roles.json`
`/windowSize <number>`	Set the context window size (in tokens) for handover logic. Persists to `roles.json`
`/globalTodo on\|off`	Toggle shared todo lists across subagents. Persists to `roles.json`
`/effort <num\|name>`	Set effort level (1-5 or zen, serious, extreme, feral, insane). Controls max subagent depth
`/help`	Show available in-chat commands
`!<command>`	Run a shell command directly (e.g. `!ls -la`, `!pytest tests/`)

Persistence and defaults

/streaming, /reasoning, /windowSize, and /globalTodo take effect on the next message and persist to ~/.config/raggie/roles.json so they survive across sessions.
Calling /streaming, /reasoning, /windowSize, or /globalTodo without arguments shows the current value.
Calling /effort without arguments prompts you to pick a level interactively.
Shell commands via ! execute in the project directory. Output is printed directly and does not go through the LLM.

Undo and Redo Flow

After every agent response, all changed files are committed to the built-in git repo at .raggie/git/. The undo/redo commands make this versioning immediately accessible.

                  
                  Chat
                
                  Agent: Done! Created utils/stats.py with calculate_stats().
  type /undo to undo the last code changes

You: /undo
  Undoing last commit...
  Restored previous state. utils/stats.py removed.

You: /redo
  Re-applying last undone commit...
  Restored. utils/stats.py is back.

Changing Effort Mid-Session

The current effort level is shown before each prompt. You can change it at any time:

                  /effort 3        # set by number
/effort extreme  # set by name (case-insensitive)
/effort          # interactive prompt to pick a level
                

Effort Levels

Effort levels control how deep the agent can nest subagents. Higher effort means the agent can break down complex tasks into more layers of subtasks .; at the cost of more API calls and tokens. New sessions default to Zen (level 1), which is still powerful: the agent delegates work through the todo list system in a linear, predictable way .; one task at a time, never in parallel.

Level	Name	Max Depth	Description
1	Zen	1	One level of subagents. Agent delegation still happens via the todo list .; tasks execute one by one in a linear, predictable flow. Fast and cheap. Default for new sessions.
2	Serious	2	Moderate. Up to 2 levels of nested subagents. Good for most multi-step tasks.
3	Extreme	4	Deep. Up to 4 levels of nested subagents for complex multi-step tasks.
4	Feral	8	Very deep. Up to 8 levels. For highly complex tasks requiring extensive decomposition.
5	Insane	16	Deepest. Up to 16 levels. For the most complex tasks. Use with caution.

How Depth Works

When the agent dispatches a subagent, the child session's depth increments. If the depth reaches the effort level's max_depth, further subagent dispatch and todo list creation are blocked. This prevents runaway recursion and keeps costs predictable.

                  
                  
                  
                  Depth Illustration
                

                  Effort: Extreme (max depth 4)

Main Session   (depth 0)
  |
  +-- DispatchSubagent("Migrate database schema")
      |
      Subagent A   (depth 1)
        |
        +-- DispatchSubagent("Update SQLAlchemy models")
            |
            Subagent B   (depth 2)
              |
              +-- DispatchSubagent("Update repository layer")
                  |
                  Subagent C   (depth 3)
                    |
                    +-- DispatchSubagent("Update API serializers")
                        |
                        Subagent D   (depth 4)     ← max depth reached
                        DispatchSubagent blocked: max depth (4) reached
                

Changing Effort

In interactive mode:

                      /effort 3        # set by number
/effort extreme  # set by name (case-insensitive)
/effort          # interactive prompt to pick a level
                    

In non-interactive mode (CLI flag):

raggie code myproject --prompt "Refactor everything" --effort 5

New sessions default to Zen (level 1) .; still powerful, just linear and predictable. The effort level persists per session in the database.