doc/user/gitlab_duo_cli/_index.md
{{< details >}}
{{< /details >}}
{{< collapsible title="Model information" >}}
{{< /collapsible >}}
{{< history >}}
glab 1.87.0, during the GitLab 18.9 release./exit slash command introduced in GitLab Duo CLI 8.88.0, during the GitLab 19.0 release./doctor slash command introduced in GitLab Duo CLI 8.94.0, during the GitLab 19.0 release./skills slash command introduced in GitLab Duo CLI 8.81.0, during the GitLab 19.0 release./mcp slash command introduced in GitLab Duo CLI 8.95.0, during the GitLab 19.0 release.AI_AGENT environment variable introduced in GitLab Duo CLI 8.95.0, during the GitLab 19.0 release.{{< /history >}}
The GitLab Duo CLI is a command-line interface tool that brings GitLab Duo Agentic Chat to your terminal. Available for use with any operating system and editor, use the CLI to ask complex questions about your codebase and to autonomously perform actions on your behalf.
The GitLab Duo CLI can help you:
[!note] The GitLab Duo CLI is now generally available. Update to GitLab Duo CLI 9.0.0 or later for the full generally available experience.
The GitLab Duo CLI offers two modes:
It also supports custom instructions set for
the GitLab Duo Agent Platform, including chat-rules.md, AGENTS.md, and SKILL.md files.
[!note] If you are on GitLab 18.11 to 19.1, you can use the latest version of the GitLab Duo CLI by turning on beta and experimental features.
{{< details >}}
{{< /details >}}
{{< history >}}
{{< /history >}}
By default, GitLab Duo CLI access is turned on.
On GitLab Self-Managed and GitLab Dedicated, you can turn GitLab Duo CLI access on or off for an instance.
Prerequisites:
You can use the GitLab Duo CLI through the GitLab CLI (glab). With the GitLab CLI, you get access to other GitLab features and you only need to authenticate once, using OAuth and or a personal access token.
Alternatively, you can install and use the GitLab Duo CLI (duo) as a standalone AI tool, authenticating
separately with a personal access token.
Both setups support interactive and headless modes, along with all GitLab Duo CLI options, commands and functionality.
Prerequisites:
To set up the GitLab Duo CLI for use through the GitLab CLI:
Run the glab command for the GitLab Duo CLI:
glab duo cli
Follow the prompts to install the GitLab Duo CLI binary.
The GitLab CLI automatically handles authentication, so you can start using the GitLab Duo CLI immediately.
To use the GitLab Duo CLI as a standalone tool, install it and then authenticate.
To install the GitLab Duo CLI as a compiled binary, download and run the install script.
On macOS and Linux:
bash <(curl --fail --silent --show-error --location "https://gitlab.com/gitlab-org/editor-extensions/gitlab-lsp/-/raw/main/packages/cli/scripts/install_duo_cli.sh")
On Windows:
irm "https://gitlab.com/gitlab-org/editor-extensions/gitlab-lsp/-/raw/main/packages/cli/scripts/install_duo_cli.ps1" | iex
[!note] If
glabis already installed and authenticated on your system when you first runduo,duoautomatically usesglabas a credential helper. You do not need to authenticate separately. This requiresglab1.85.2 or later andduo8.68.0 or later.If you authenticated
duobefore this feature was available and want to useglabas a credential helper instead, delete your authentication settings from~/.gitlab/storage.json.
Prerequisites:
api permissions.To authenticate:
duo in your terminal. The first time you run the GitLab Duo CLI, a configuration screen
appears.https://gitlab.com.duo in your terminal.To modify the configuration after initial setup, use duo config edit.
Prerequisites:
api permissions.To authenticate with environment variables:
Set GITLAB_TOKEN or GITLAB_OAUTH_TOKEN to your personal access token.
export GITLAB_TOKEN="<your-personal-access-token>"
Optional. Set GITLAB_BASE_URL or GITLAB_URL to your custom GitLab instance URL, for example https://gitlab.example.com. The default is https://gitlab.com.
export GITLAB_BASE_URL="<your-instance-url>"
This method is useful for headless mode, CI/CD pipelines, and scripted workflows where interactive authentication is not possible.
Prerequisites:
To use the GitLab Duo CLI in interactive mode:
Based on your setup, enter the command to start interactive mode:
{{< tabs >}}
{{< tab title="glab" >}}
glab duo cli
{{< /tab >}}
{{< tab title="duo" >}}
duo
{{< /tab >}}
{{< /tabs >}}
The prompt > appears in your terminal window. After the prompt, enter your question or
request and press <kbd>Enter</kbd>.
For example:
What is this repository about?
Which issues need my attention?
Help me implement issue 15.
The pipelines in MR 23 are failing. Please help me fix them.
To cancel a response while the GitLab Duo CLI is working, press <kbd>Escape</kbd>. The GitLab Duo CLI stops the current operation and returns to the prompt.
Use the <kbd>↑</kbd> key to view your prompt history, or <kbd>Control</kbd>+<kbd>R</kbd> to search it.
In interactive mode, you can switch the GitLab Duo CLI between two modes as you work:
| Mode | Permissions | How it works |
|---|---|---|
| Build mode (default) | Read-write | GitLab Duo can execute tasks and make changes to your project. |
| Plan mode | Read-only | GitLab Duo can analyze your project and create plans without making changes. |
For example, start by discussing a problem with GitLab Duo in plan mode. When you're ready, switch to build mode and instruct GitLab Duo to implement the plan.
The GitLab Duo CLI displays the current mode under the > prompt. To switch between modes, press
<kbd>Tab</kbd>.
In interactive mode, use slash commands to configure the GitLab Duo CLI and perform actions. Enter a slash command at the prompt and press <kbd>Enter</kbd>.
The following slash commands are available:
| Command | Description |
|---|---|
/copy | Copy the last GitLab Duo response to the clipboard. |
/doctor | Show diagnostics for the GitLab Duo CLI environment. |
/exit | Exit the GitLab Duo CLI. |
/feedback | Submit a bug report or feature request. |
/help | Display a list of available slash commands. |
/mcp | View configured MCP servers and their status. |
/model | Switch the AI model for the current session. |
/new | Start a new chat session. |
/sessions | Browse, search, and switch sessions. |
/settings | Open the settings panel. |
/skills | List available Agent Skills in the current project. |
You can also create your own slash commands. For more information, see custom slash commands.
To change a setting:
/settings and press <kbd>Enter</kbd>.Changes persist across sessions.
The following settings are available:
| Setting | Description |
|---|---|
| Telemetry | Send anonymous usage data to improve GitLab Duo. |
| Enable global skills | (Experimental) Discover user-level Agent Skills from ~/.agents/skills/ and ~/.gitlab/duo/skills/. A restart is required for changes to take effect. |
| Notifications | Control system notifications (auto or disabled). |
The GitLab Duo CLI can send a system notification when a session needs your attention (for example, when it finishes a task or requires a tool approval) while the terminal window is not focused.
Notifications are controlled by the Notifications setting in the settings panel:
auto (default): Send a system notification when the terminal is unfocused.disabled: Never send system notifications.When GitLab Duo needs to use a tool, it prompts you to approve before it begins. For example, when it needs to read a file or run a command.
Your options are:
[!note] To use the Approve for session option, your administrator must turn it on for your group or instance. For more information, see tool approvals.
[!caution] Use headless mode with caution and in a controlled sandbox environment.
To run a workflow in non-interactive mode, use the command for your setup:
{{< tabs >}}
{{< tab title="glab" >}}
Use glab duo cli run:
glab duo cli run --goal "Your goal or prompt here"
For example, you can run an ESLint command and pipe errors to the GitLab Duo CLI to resolve:
glab duo cli run --goal "Fix these errors: $eslint_output"
{{< /tab >}}
{{< tab title="duo" >}}
Use duo run:
duo run --goal "Your goal or prompt here"
For example, you can run an ESLint command and pipe errors to the GitLab Duo CLI to resolve:
duo run --goal "Fix these errors: $eslint_output"
{{< /tab >}}
{{< /tabs >}}
When you use headless mode, the GitLab Duo CLI:
run command.You can select a model for interactive mode or headless mode.
The model you select persists across sessions, and you can switch models mid-conversation without losing context.
Prerequisites:
To select a model for interactive mode:
/model and press <kbd>Enter</kbd>.The model you select does not persist across sessions.
Prerequisites:
To select a model for headless mode:
Find the gitlab_identifier for the model.
When you run the GitLab Duo CLI, set the --model option or the GITLAB_DUO_MODEL environment
variable to the gitlab_identifier value.
{{< tabs >}}
{{< tab title="glab" >}}
Use the --model option:
glab duo cli --model <gitlab_identifier_for_the_model>
Use the GITLAB_DUO_MODEL environment variable:
GITLAB_DUO_MODEL=<gitlab_identifier_for_the_model> glab duo cli
For example, to use GPT-5-Codex - OpenAI:
glab duo cli --model gpt_5_codex
GITLAB_DUO_MODEL=gpt_5_codex glab duo cli
{{< /tab >}}
{{< tab title="duo" >}}
Use the --model option:
duo --model <gitlab_identifier_for_the_model>
Use the GITLAB_DUO_MODEL environment variable:
GITLAB_DUO_MODEL=<gitlab_identifier_for_the_model> duo
For example, to use GPT-5-Codex - OpenAI:
duo --model gpt_5_codex
GITLAB_DUO_MODEL=gpt_5_codex duo
{{< /tab >}}
{{< /tabs >}}
GitLab Duo Chat sessions store your conversation history and workflow data, and are shared across the GitLab Duo CLI, the GitLab UI, and editor extensions.
For example, you can start a conversation in your browser and continue it in your terminal.
To browse and switch to a session:
/sessions and press <kbd>Enter</kbd>.To switch to a session in headless mode, use the --existing-session-id option.
To connect the GitLab Duo CLI to local or remote MCP servers, use the same MCP configuration as the GitLab IDE extensions. For instructions, see configure MCP servers.
{{< details >}}
{{< /details >}}
{{< history >}}
{{< /history >}}
Use hooks to run custom commands at specific points in the GitLab Duo CLI lifecycle.
For example, you can inject additional context into every new chat session by running a script that gathers information about your environment.
The GitLab Duo CLI supports hooks at two levels:
When both user-level and project-level hooks.json files exist, the CLI merges the hooks and runs
the user-level ones first.
[!note] For security reasons, sensitive environment variables (
GITLAB_TOKEN,GITLAB_OAUTH_TOKEN,CI_JOB_TOKEN) are excluded from hook processes.
When a hook runs, the GitLab Duo CLI:
Sends a JSON object to the command's standard input with session metadata:
{
"session_id": "abc-123",
"cwd": "/path/to/project",
"transcript_path": "",
"hook_event_name": "SessionStart",
"source": "startup"
}
Sets environment variables DUO_SESSION_ID and DUO_PROJECT_DIR for the
hook process.
Collects the command's standard output as additional context for the session.
The hook can return plain text on standard output, or a JSON object:
{
"hookSpecificOutput": {
"hookEventName": "SessionStart",
"additionalContext": "Your context string here"
}
}
If the hook exits with a non-zero status or times out, it is logged as a warning but does not block the session from starting.
The GitLab Duo CLI supports the SessionStart event, which runs when a new session starts or an existing
session resumes.
To create a hook:
Create a hooks.json file:
~/.gitlab/duo/hooks.json.%APPDATA%\GitLab\duo\hooks.json.<project>/.gitlab/duo/hooks.json.Define your hooks in the file.
Create a matcher group for each SessionStart event source that should trigger the hook (startup
or resume).
Each matcher group has an optional regex matcher value and an array of command hooks:
| Field | Description |
|---|---|
matcher | Optional. Regex tested against the event source (startup or resume for SessionStart). Omit to match all. |
hooks[].type | Must be "command". |
hooks[].command | A shell command to execute. |
hooks[].timeout | Optional. Timeout in seconds. Default: 30. |
For example:
{
"hooks": {
"SessionStart": [
{
"matcher": "startup",
"hooks": [
{
"type": "command",
"command": "cat ~/.my-coding-preferences.md",
"timeout": 10
}
]
}
]
}
}
If you have project-level hooks, enable them when you start the GitLab Duo CLI:
{{< tabs >}}
{{< tab title="glab" >}}
glab duo cli --enable-project-hooks
{{< /tab >}}
{{< tab title="duo" >}}
duo --enable-project-hooks
{{< /tab >}}
{{< /tabs >}}
Alternatively, set the environment variable:
export GITLAB_ENABLE_PROJECT_HOOKS=true
{{< history >}}
{{< /history >}}
Create custom slash commands for prompts you use frequently.
The GitLab Duo CLI supports custom slash commands at two levels:
If a user-level command and a project-level command share the same name, the project-level command takes precedence. Custom slash commands cannot override built-in slash commands or Agent Skills slash commands.
To create a custom slash command, you create a Markdown file.
The filename is the command name, and the file content is the prompt.
For example, a file named daily.md creates the /daily command:
Create a commands directory:
<project>/.agents/commands/.~/.gitlab/duo/commands/.%APPDATA%\GitLab\duo\commands\.GLAB_CONFIG_DIR or XDG_CONFIG_HOME, use $GLAB_CONFIG_DIR/commands/
or $XDG_CONFIG_HOME/gitlab/duo/commands/. If both are set, GLAB_CONFIG_DIR takes
priority.~/.agents/commands/.%USERPROFILE%\.agents\commands\.In the directory, create a Markdown file. Use the command name as the filename. Command names must start with a letter or number, and can contain only letters, numbers, hyphens, and underscores.
Add the prompt to the file.
Optional. Add a description field in YAML front matter at the top of the file.
The description appears next to the command in the slash command menu.
For example, a /daily command defined in daily.md:
---
description: Prepare a daily report
---
Use `glab todo list` to fetch my open TODO items. Give me a concise morning report ranked by priority.
Restart the GitLab Duo CLI. The CLI discovers custom slash commands when it starts.
In interactive mode, enter the slash command at the prompt and press <kbd>Enter</kbd>. The GitLab Duo CLI sends the file content as the prompt.
Any text you enter after the command name is added to the end of the prompt.
Use this to customize what the custom slash command does.
For example, /daily prioritize my milestone deliverables.
Use these options, commands, and environment variables when you start or run the GitLab Duo CLI.
For more details and the most up-to-date list, see the GitLab Duo CLI reference.
The GitLab Duo CLI supports these options:
-C, --cwd <path>: Change the working directory.-h, --help : Display help for the GitLab Duo CLI or a specific command. For example, duo --help or
duo run --help.--log-level <level>: Set the logging level (debug, info, warn, error).-v, --version: Display version information.--enable-global-skills: (Experimental) Enable user-level Agent Skills.--enable-project-hooks: (Experimental) Enable loading project-level hooks.--model <model>: Select the AI model to use for the session.Additional options for headless mode:
--ai-context-items <contextItems>: JSON-encoded array of additional context items for reference.--existing-session-id <sessionId>: ID of an existing session to resume.--gitlab-auth-token <token>: Authentication token for a GitLab instance.--gitlab-base-url <url>: Base URL of a GitLab instance (default: https://gitlab.com).The following commands are available for each setup:
{{< tabs >}}
{{< tab title="glab" >}}
glab duo cli: Start interactive mode.glab duo cli log: View and manage logs.
glab duo cli log last: Open the last log file.glab duo cli log list: List all log files.glab duo cli log tail <args...>: Display the tail of the last log file.
Supports standard tail arguments.glab duo cli log clear: Remove all existing log files.glab duo cli run: Start headless mode.{{< /tab >}}
{{< tab title="duo" >}}
duo: Start interactive mode.duo config: Manage the configuration and authentication settings.duo log: View and manage logs.
duo log last: Open the last log file.duo log list: List all log files.duo log tail <args...>: Display the tail of the last log file.
Supports standard tail arguments.duo log clear: Remove all existing log files.duo run: Start headless mode.{{< /tab >}}
{{< /tabs >}}
You can configure the GitLab Duo CLI using environment variables:
DUO_WORKFLOW_GIT_HTTP_PASSWORD: Git HTTP authentication password.DUO_WORKFLOW_GIT_HTTP_USER: Git HTTP authentication username.GITLAB_BASE_URL or GITLAB_URL: GitLab instance URL.GITLAB_DUO_MODEL: AI model to use for the session.GITLAB_ENABLE_GLOBAL_SKILLS: (Experimental) Enable user-level Agent Skills.GITLAB_ENABLE_PROJECT_HOOKS: (Experimental) Enable loading project-level hooks.GITLAB_OAUTH_TOKEN or GITLAB_TOKEN: Authentication token.LOG_LEVEL: Logging level.When the GitLab Duo CLI runs a command on your behalf, it sets the AI_AGENT environment variable
in that process. Scripts and tools can read AI_AGENT to detect that they are running in an
AI-driven execution.
If your network uses an HTTPS-intercepting proxy or requires custom SSL certificates, you might need additional configuration.
The GitLab Duo CLI respects standard proxy environment variables:
HTTP_PROXY or http_proxy: Proxy URL for HTTP requests.HTTPS_PROXY or https_proxy: Proxy URL for HTTPS requests.NO_PROXY or no_proxy: Comma-separated list of hosts to exclude from proxying.If your organization uses a custom Certificate Authority (CA), for an HTTPS-intercepting proxy or similar, you might encounter certificate errors.
Error: unable to verify the first certificate
Error: self-signed certificate in certificate chain
To resolve certificate errors, use one of the following methods:
Use the system certificate store (recommended):
export NODE_OPTIONS="--use-system-ca"
Specify a CA certificate file:
export NODE_EXTRA_CA_CERTS=/path/to/custom-ca.pem
If you still encounter certificate errors, you can disable certificate verification.
[!warning] Disabling certificate verification is a security risk. You should not disable verification in production environments.
Certificate errors alert you to potential security breaches, so you should disable certificate verification only when you are confident that it is safe to do so.
Prerequisites:
To disable certificate verification:
export NODE_TLS_REJECT_UNAUTHORIZED=0
To manually update the GitLab Duo CLI to the latest version, run the command for your setup:
{{< tabs >}}
{{< tab title="glab" >}}
glab duo cli --update
{{< /tab >}}
{{< tab title="duo" >}}
npm install --global @gitlab/duo-cli@latest
{{< /tab >}}
{{< /tabs >}}
For information on contributing to the GitLab Duo CLI, see the development guide.