Work with the CLI

Once the CLI is installed and your API key is set, you're ready for day-to-day work. The CLI runs in two modes: interactive for chat and exploration, and programmatic for scripting and CI.

Navigate to your project root and run:

vibe

vibe

You can also start with an initial prompt:

vibe "Refactor the main function in cli/main.py to be more modular."

vibe "Refactor the main function in cli/main.py to be more modular."

The CLI launches a terminal chat interface. From there, you can iterate on coding tasks, reference files, run shell commands, and switch agents without leaving the terminal.

Interactive mode is the default. Use it for exploration, multi-step tasks, and any work that benefits from review and follow-up.

Prefix a path with @ to attach a file to your prompt. The CLI provides autocompletion as you type:

> Read the file @src/agent.py and suggest improvements.

> Read the file @src/agent.py and suggest improvements.

To attach an image, @-mention it or paste its file path. On macOS, you can also paste an image from the clipboard with Ctrl+V or /paste-image. Images work when the active model supports them or when a vision_model is configured. Otherwise, the model receives [Image] and a link to the image file instead.

Type / to open the slash-command picker with autocompletion. Use it for built-in commands like /help, /model, /config, or any command exposed by an installed skill. See Commands and shortcuts for the full list.

> /model

> /model

Prefix a command with ! to run it directly in your shell, bypassing the agent:

> !ls -l

> !ls -l

The agent sees the command and its output as context for your next message.

Prefix a prompt with & to run it in a Vibe Code Web sandbox. The CLI returns a link to the cloud session.

> & fix the failing tests

> & fix the failing tests

See Teleport from CLI to web for prerequisites and limits.

Press Enter while the agent works to queue a message. Vibe sends all queued messages together when the turn ends. To hand them to the agent before the turn ends, press Enter again with an empty input.

Press Up to select a queued message, then Enter to edit it or Backspace to remove it. Escape interrupts the agent and pauses the queue; press Enter to send the paused messages. Shell (!) commands and most slash commands wait until the agent is idle. Read-only commands such as /status and display settings such as /theme run right away.

See Commands and shortcuts for the full list of slash commands and shortcuts.

The footer shows the active model and its thinking level. Click the model to open /model.

Programmatic mode is built for scripting, CI jobs, and any non-interactive use. Use the --prompt (-p) flag to run a single task and exit:

vibe --prompt "Analyze the codebase" --max-turns 5 --output json

vibe --prompt "Analyze the codebase" --max-turns 5 --output json

You can also read the prompt from a file with --prompt-file PATH, or pipe it on stdin with -p and no text.

Programmatic mode doesn't start the chat interface and disables interactive tools such as the question prompt. It runs with your default_agent (accept-edits unless you change it). Nobody can answer an approval prompt, so Vibe denies any tool call that needs one. To approve every tool call, pass --auto-approve (or its alias --yolo):

vibe --prompt "Fix the failing tests" --auto-approve

vibe --prompt "Fix the failing tests" --auto-approve

If your administrator sets enable_auto_approve = false, Vibe ignores --auto-approve. Allow the tools the run needs with permission = "always" or an allowlist instead.

Useful options:

• --model ALIAS runs a new session on that model without changing your active_model.
• --system-prompt-file PATH replaces Vibe's own instructions in the system prompt with the file's text. Project context and AGENTS.md files still follow it.
• --max-turns N caps the number of assistant turns. Recommended to bound run length.
• --max-tokens N caps the total prompt and completion tokens for the run.
• --time-limit SECONDS stops the run after a deadline. You can resume the session later. SIGTERM stops a run the same way.
• --enabled-tools TOOL restricts which tools the agent can use, and disables all others. Supports exact names, glob patterns (bash*), and regex with the re: prefix (re:^serena_.*$). Repeat the flag for several tools.
• --disabled-tools TOOL disables tools after --enabled-tools filtering. Repeat the flag for several tools.
• --output text|json|streaming sets the output format. text (default) prints the final answer, json prints the session messages as a JSON array when the run ends, and streaming prints one JSON object per message as the run progresses.
• --output-dir DIR writes an export.json file (Vibe version, effective config, token usage, cost, stop reason, and outcome) and a copy of the session to DIR, however the run ends. The export also lists each subagent with its status, model, token usage, cost, and steps, and copies its session.

Before it exits, a programmatic run waits for the subagents its last turn left running. --time-limit and other stops interrupt them.

The exit code tells you how the run ended:

The CLI ships with several built-in agents. By default, it uses accept-edits. Pick another one with --agent:

vibe --agent ask
vibe --agent smart-approve
vibe --agent auto-approve

vibe --agent ask
vibe --agent smart-approve
vibe --agent auto-approve

Switch agents mid-session (interactive mode only) with Shift+Tab. Set the default agent for interactive and programmatic sessions in config.toml:

default_agent = "ask"

default_agent = "ask"

See Agents for the full list and behavior.

For tasks with substantial file edits or shell commands, the CLI:

1. Shows a preview of the change or command before running it.
2. Asks for confirmation, unless the active agent auto-approves.
3. Displays the result after each step.

The CLI checks whether the current working directory is trusted before loading project-level configuration, skills, or agent files. The first time you run the CLI in interactive mode from a new directory that contains trustable files, it asks you to confirm the folder.

Trust enforcement applies in both interactive and programmatic modes, but the confirmation prompt only appears interactively. In programmatic mode, use vibe --trust to grant temporary trust for the current invocation only.

Trusted folders are remembered in ~/.vibe/trusted_folders.toml.

The CLI can pick up where you left off:

• vibe --continue (or -c) resumes the last session of this terminal in the current directory, or the directory's most recent session when this terminal has none there.
• vibe --resume opens a picker of past sessions.
• vibe --resume SESSION_ID resumes a specific session. Partial IDs are supported. In programmatic mode, combine -p with --continue or --resume SESSION_ID to continue a saved session.
• /resume (or /continue) inside a session opens the same picker. Press d twice to delete the highlighted session.
• /branch forks the current conversation into a new session that you can resume later, and leaves the current session unchanged.
• /rewind (or Escape twice on an empty input) goes back to an earlier message so you can edit it and continue from there.

A resumed or continued session keeps the agent it last ran on, even if your default_agent changed or you pass another --agent. Switch agents inside the session to change it. If that agent is no longer available, Vibe uses --agent or your default_agent instead.

The picker, --continue, and --resume without an ID only list sessions started in the current directory. --resume SESSION_ID works from anywhere.

To choose which terminal --continue follows, set VIBE_TERMINAL_KEY to a name of your own. Set it to an empty value to resume the directory's most recent session from any terminal.

Session continuation requires session logging, which is enabled by default. If resume stops working after editing your configuration, make sure logging is still enabled in ~/.vibe/config.toml:

[session_logging]
enabled = true

[session_logging]
enabled = true

Use --worktree to run a session in its own git worktree, so the agent's changes stay apart from your current checkout:

vibe --worktree my-feature

vibe --worktree my-feature

Vibe creates the worktree under ~/.vibe/worktrees/ on a branch named my-feature, or reuses it if it already exists. Without a name, Vibe names the worktree after your prompt. Put the prompt first, because --worktree reads the next argument as the name:

vibe "Fix the login bug" --worktree

vibe "Fix the login bug" --worktree

When an interactive session ends, Vibe removes a worktree it created if it holds no changes, and asks you otherwise. Programmatic runs leave the worktree in place.

--worktree trusts the worktree for that run, so you don't need --trust. Combine it with -c or --resume to resume a session started in that worktree.