Use the GitLab Duo CLI

Prerequisites:

• A default GitLab Duo namespace set, or an open project that has GitLab Duo access.

You can use the GitLab Duo CLI in two modes:

• Interactive mode: Provides a chat experience similar to GitLab Duo Chat in the GitLab UI or in editor extensions. Supports build and plan modes.
• Headless mode: Enables non-interactive use in runners, scripts, and other automated workflows.

Interactive mode

To use the GitLab Duo CLI in interactive mode:

1. Based on your setup, enter the command to start interactive mode:

   glab

   glab duo cli

   duo

   duo

2. The prompt > appears in your terminal window. After the prompt, enter your question or request and press Enter.

   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 Escape. The GitLab Duo CLI stops the current operation and returns to the prompt.

Use the ↑ key to view your prompt history, or Control+R to search it.

Switch between build and plan modes

In interactive mode, you can switch the GitLab Duo CLI between two modes as you work:

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 Tab.

Slash commands

In interactive mode, use slash commands to configure the GitLab Duo CLI and perform actions. Enter a slash command at the prompt and press Enter.

The following slash commands are available:

You can also create your own slash commands. For more information, see custom slash commands.

Settings

To change a setting:

1. In interactive mode, type /settings and press Enter.
2. Use the arrow keys to navigate the list of settings.
3. To change the selected setting, press Enter or Space.
4. To close the panel, press Escape.

Changes persist across sessions.

The following settings are available:

System notifications

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.

Tool approvals

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:

• Approve: GitLab Duo can use the tool once.
• Approve for session: GitLab Duo can use the tool with these arguments for the remainder of the session. Different arguments require additional approval.
• Deny: GitLab Duo cannot use the tool.

Headless mode

To run a workflow in non-interactive mode, use the command for your setup:

glab duo cli run --goal "Your goal or prompt here"

glab duo cli run --goal "Fix these errors: $eslint_output"

duo run --goal "Your goal or prompt here"

duo run --goal "Fix these errors: $eslint_output"

When you use headless mode, the GitLab Duo CLI:

• Bypasses manual tool approvals and automatically approves all tools for use.
• Does not maintain context from previous conversations. A new workflow starts every time you execute the run command.

Select a model

You can select a model for interactive mode or headless mode.

For interactive mode

The model you select persists across sessions, and you can switch models mid-conversation without losing context.

Prerequisites:

• GitLab Duo CLI 8.76.0 or later.

To select a model for interactive mode:

1. In interactive mode, type /model and press Enter.
2. Use the arrow keys to scroll through the list of available models, or enter a model name to filter the list.
3. Select a model and press Enter to switch to it.

For headless mode

The model you select does not persist across sessions.

Prerequisites:

• GitLab Duo CLI 8.68.0 or later.

To select a model for headless mode:

1. Find the gitlab_identifier for the model.

2. When you run the GitLab Duo CLI, set the --model option or the GITLAB_DUO_MODEL environment variable to the gitlab_identifier value.

   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

   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

Switch sessions

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:

1. In interactive mode, type /sessions and press Enter.
2. Use the arrow keys to scroll through the list of available sessions, or enter text to filter the list.
3. Select a session and press Enter.

To switch to a session in headless mode, use the --existing-session-id option.

Model Context Protocol (MCP) connections

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.

Related topics

• GitLab Duo CLI complete reference
• Security considerations for editor extensions
• GitLab CLI
• Customize GitLab Duo Agent Platform
• GitLab Duo Agent Platform sessions

Troubleshooting

When working with the GitLab Duo CLI, you might encounter the following issues.

Certificate errors

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):

  1. 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.

  2. 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:

  1. 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.

  2. 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

Ignore certificate errors

If you still encounter certificate errors, you can disable certificate verification.

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:

• You verified the certificate chain in your browser, or your administrator confirmed that this error is safe to ignore.

To disable certificate verification:

export NODE_TLS_REJECT_UNAUTHORIZED=0