How to Use Mistral Vibe CLI for Agentic Coding Directly from Your Terminal

Software engineers frequently face a frustrating bottleneck when using web-based AI coding tools: the friction of constantly switching between browser tabs and the terminal, manually copying stack traces, and stitching fragmented code diffs back into local files. Mistral Vibe (mistral-vibe) eliminates this context switching by providing an open-source, terminal-native AI coding agent powered by Mistral AI's models.

By operating directly inside your project directory, Mistral Vibe reads your codebase structure, understands Git branch context, drafts multi-file code modifications through unified patches, and executes test suites in managed shell sessions—all driven by natural language prompts from your command line.

1. Prerequisites and Installation

Mistral Vibe is designed for modern terminal environments. While Linux and macOS are officially targeted, Windows is supported through uv or PowerShell environments.

System Requirements

• Python 3.10+ (if installing via Python package managers).
• A modern terminal emulator with UTF-8 and ANSI support (such as Ghostty, WezTerm, Kitty, or Alacritty).
• A Mistral AI API key (obtainable from the Mistral AI Console) or an active Mistral subscription.

Installation Options

You can install Mistral Vibe using any of the following methods:

Method 1: One-Line Shell Script (macOS and Linux Recommended)

curl -LsSf https://mistral.ai/vibe/install.sh | bash

Method 2: Using uv (Fastest, Isolated Python Environment)

uv tool install mistral-vibe

Method 3: Standard pip Installation

pip install mistral-vibe

Initial Setup and Authentication

To configure your API credentials and environment, run the interactive setup wizard:

vibe --setup

The wizard prompts you for your MISTRAL_API_KEY and securely saves it to ~/.vibe/.env. Alternatively, you can export the key directly in your shell configuration (~/.bashrc or ~/.zshrc):

export MISTRAL_API_KEY="your-mistral-api-key-here"

When you first launch Vibe inside a new repository containing local configurations, Vibe's Trust Folder system prompts you to confirm that you trust the current workspace. Once approved, the directory is registered in ~/.vibe/trusted_folders.toml.

2. Core Concepts: Agent Profiles and Safety Modes

Autonomous agents require clear operational boundaries. Mistral Vibe ships with built-in agent profiles that control whether the agent can read files, write edits, or execute arbitrary terminal commands without human confirmation.

You can specify the agent profile when starting a session:

vibe --agent plan

Inside an active interactive session, you can cycle between available profiles at any time by pressing Shift+Tab.

3. Navigating the Interactive Terminal Interface

Starting Mistral Vibe is as simple as navigating to your repository's root directory and running:

cd /path/to/my-project
vibe

Mistral Vibe launches a rich Terminal User Interface (TUI). It automatically loads your project root, Git branch, and recent commit history into the agent's baseline context.

Command Line Syntax Primitives

Within the interactive prompt, you can use specialized syntax to manage context and execution:

• @path/to/file: References a specific file or folder. Autocomplete surfaces tracked Git files. You can also reference image files (.png, .jpg, .webp), which are passed natively to multimodal vision models.
• !command: Shell escape prefix. Executes commands directly on your local system without sending them to the LLM (for example, !git diff or !pytest).
• /: Opens the slash command picker for session management.

Key Slash Commands

• /model: Switch the active foundation model (such as mistral-medium-3.5 or codestral-latest).
• /config: Open the interactive configuration editor.
• /mcp or /connectors: Inspect active Model Context Protocol (MCP) servers and external data tools.
• /loop [interval/schedule]: Set recurring automated tasks (for example, /loop every five minutes check git status and test).
• /retry [instructions]: Resume and steer an interrupted generation.
• /clear: Clear current chat context history.
• /exit (or :q): Safely terminate the session.

TUI Hotkeys for Fast Control

• Shift+Tab: Cycle through agent profiles (accept-edits, plan, ask).
• Ctrl+O: Toggle the detailed tool execution output panel.
• Ctrl+T: Toggle the agent's internal todo list tracker.
• Ctrl+G: Open your default external text editor ($EDITOR) to draft long, multi-paragraph prompts.
• Escape: Interrupt an active generation turn.

4. Executing Agentic Coding Workflows

Mistral Vibe shines across three primary engineering workflows: architecture exploration, new feature scaffolding, and multi-file refactoring.

Workflow 1: Safe Codebase Exploration with Subagents

When entering an unfamiliar codebase, you can inspect architecture without risking accidental modifications:

vibe --agent plan

Prompt example:

Trace how authentication middleware handles JWT verification and identify where user claims are attached to incoming requests.

The agent uses grep and read tools to scan the repository. For larger tasks, Vibe delegates background indexing to its built-in explore subagent via the task() tool. Subagents work independently in isolated contexts, preventing the main conversation window from exhausting its token limit.

Workflow 2: Multi-File Scaffolding and Boilerplate Generation

Mistral Vibe can generate complete application features across multiple directories in a single request:

Scaffold a complete health-check and metrics subsystem in src/monitoring/:
1. Create src/monitoring/health.py with system resource checks (CPU, memory, disk).
2. Create src/monitoring/metrics.py exposing Prometheus gauge counters.
3. Wire the new health router into src/main.py.
4. Add comprehensive unit tests under tests/test_monitoring.py.

Under the default accept-edits mode:

1. Vibe inspects src/main.py using read.
2. Vibe writes the new files using write_file.
3. Vibe modifies src/main.py using edit, applying clean surgical diffs without rewriting unaffected functions.
4. Vibe asks your permission before running test commands.

Workflow 3: Multi-File Refactoring and the Autonomous Test-Fix Loop

Refactoring requires editing interdependent files and verifying that existing functionality remains intact.

Prompt example:

Refactor our database session handling in @src/services/user_service.py and @src/services/order_service.py from synchronous sessions to async SQLAlchemy sessions. Update the service methods, adapt the route handlers in @src/api/routes.py, and run the test suite to verify everything passes.

The agent executes the refactoring cycle:

1. Inspection: Reads service definitions, route signatures, and test cases.
2. Patch Application: Applies edits across the services and API handlers.
3. Execution: Issues a shell execution request to run pytest tests/.
4. Iterative Self-Correction: If a test fails with an AsyncSession error, Vibe captures stdout and stderr, diagnoses the issue, patches the failing query, and reruns pytest until all tests pass.

5. Customizing Projects with AGENTS.md, Skills, and MCP

To ensure Mistral Vibe adheres to your team's specific coding guidelines, you can customize agent behavior at both global and project levels.

Steering Behavior with AGENTS.md

Mistral Vibe automatically injects instructions from AGENTS.md files into the model's system prompt:

• ~/.vibe/AGENTS.md: Global instructions applied to every project on your workstation.
• ./AGENTS.md: Repository-specific instructions located in your project root.

A practical project AGENTS.md might look like:

# Repository Engineering Guidelines

- Always write type hints adhering to Python 3.12 syntax.
- Use pytest with asyncio_mode = "auto" for asynchronous unit tests.
- Never modify database migration files in `alembic/versions/` without explicit instruction.
- Format all code with `ruff format` before completing any task.

Extending Capabilities with Custom Skills

Vibe follows the Agent Skills open standard. You can define custom reusable slash commands by creating a SKILL.md file in .vibe/skills/<skill-name>/ or .agents/skills/<skill-name>/:

---
name: security-audit
description: Scan repository for hardcoded secrets and vulnerable dependencies
user-invocable: true
allowed-tools:
  - read
  - grep
  - bash
---

# Security Audit Skill
Run dependency vulnerability checks using pip-audit and scan codebase for hardcoded tokens.

Once defined, typing /security-audit in the interactive prompt triggers the workflow immediately.

6. Programmatic Mode and CI/CD Automation

Beyond interactive development, Mistral Vibe can execute tasks headlessly for automated workflows, code review bots, and CI/CD pipelines.

Run non-interactive tasks using the -p or --prompt flag:

vibe --prompt "Review all modified files in git diff HEAD~1, fix formatting violations, and update README.md if API signatures changed" \
     --auto-approve \
     --max-turns 10 \
     --max-price 1.50 \
     --output json \
     --output-dir ./ci-artifacts/

Safety and Budget Controls in Headless Mode

• --max-turns N: Stops execution after N assistant turns to prevent infinite loops.
• --max-price DOLLARS: Enforces a strict spending ceiling in USD.
• --max-tokens N: Enforces a maximum total token budget.
• --time-limit SECONDS: Imposes a hard execution timeout.
• --output FORMAT: Outputs structured data as text, json, or newline-delimited streaming JSON.
• --output-dir DIR: Exports execution metadata (export.json), token usage, and session transcripts for audit trails.

7. Best Practices for Terminal-Native Agentic Coding

1. Commit Before Triggering Major Edits: While Vibe provides tool rollbacks and approval prompts, keeping your Git working tree clean before large refactoring tasks allows you to use git diff or git checkout as a definitive safety net.
2. Anchor Ambiguous Requests with @ References: When requesting changes across a large project, tag core interfaces with @ (e.g., @src/core/config.py) to keep the agent focused on relevant context and save token budget.
3. Start in plan Mode for Complex Tasks: For major structural overhauls, let vibe --agent plan propose an implementation plan first. Review the plan, then switch to accept-edits to execute the changes.
4. Rely on the Test Loop: Instead of manually verifying diffs line by line, instruct the agent to run your project's test and lint commands. Let the agent interpret the test output and resolve its own regressions.

References

• GitHub - mistralai/mistral-vibe: Minimal CLI coding agent by Mistral
• Mistral AI Documentation
• Mistral AI Console
• Agent Skills: An open format for skills