doc/user/gitlab_duo_cli/use.md
{{< details >}}
{{< /details >}}
Prerequisites:
You can use the GitLab Duo CLI in two modes:
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>.
{{< history >}}
/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.{{< /history >}}
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.
{{< history >}}
{{< /history >}}
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). |
{{< history >}}
{{< /history >}}
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.{{< history >}}
{{< /history >}}
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.{{< history >}}
{{< /history >}}
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.
When working with the GitLab Duo CLI, you might encounter the following issues.
You might encounter certificate errors:
Error: unable to verify the first certificate
Error: self-signed certificate in certificate chain
These errors occur if your organization uses a custom Certificate Authority (CA) for an HTTPS-intercepting proxy or similar.
To resolve certificate errors, use one of the following methods:
Use the system certificate store (recommended):
If your CA certificate is installed in your operating system's certificate store, configure Node.js to use it. Requires Node.js 22.15.0, 23.9.0, or 24.0.0 and later.
If you run the GitLab Duo CLI in a container, install the CA certificate in the container's system store, not the host system store.
export NODE_OPTIONS="--use-system-ca"
Specify a CA certificate file:
For older Node.js versions, or when the CA certificate is not in the system store, point Node.js to the certificate file directly. The file must be in PEM format.
If you run the GitLab Duo CLI in a container, set the path to a location in the container. Use a volume mount to provide the 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 disabling verification is safe.
Prerequisites:
To disable certificate verification:
export NODE_TLS_REJECT_UNAUTHORIZED=0