Use the GitLab Duo CLI

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, plan, and auto modes.
• Headless mode: Enables non-interactive use in runners, scripts, and other automated workflows.

Prerequisites

• The GitLab Duo CLI installed and set up.
• A default GitLab Duo namespace set, or an open project that has access to GitLab Duo.

Interactive mode

To use the GitLab Duo CLI in interactive mode:

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

   glab

   shell

   glab duo cli

   duo

   shell

   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 modes

In interactive mode, you can switch the GitLab Duo CLI between 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.

Auto mode

In auto mode, GitLab Duo uses tools without asking for approval. Where your settings allow it, GitLab Duo can perform the following actions:

• Run any shell command, including commands that delete files or change your system.
• Run git commands, including commits and pushes.
• Create or update issues, merge requests, and other GitLab resources.
• Run MCP tools and start flows.

Auto mode does not override agent tool governance. Tools set to Always Deny stay blocked.

Turn on auto mode

The Auto mode setting is off by default. Auto mode must be turned on for your group or project before you can use it. Subgroups and projects inherit the setting from their parent group.

Use auto mode

Prerequisites:

• GitLab Duo CLI 9.22.0 or later.
• Auto mode turned on for your project.

To use auto mode:

1. Start or restart the GitLab Duo CLI in your project to pick up the setting.
2. Press Tab until the mode under the > prompt shows auto.
3. Enter your prompt. Auto mode applies from that prompt onward.

To stop using auto mode, press Tab to switch to another mode. The change applies to your next prompt.

Auto mode does not persist between sessions. Each new or resumed session, including a session you start with /new, starts in build mode.

Troubleshooting auto mode

If auto does not appear when you press Tab:

1. Confirm that the Auto mode setting is turned on for your project.
2. Confirm that no parent group is set to Always off.
3. Restart the GitLab Duo CLI.

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:

   shell

   glab duo cli --model <gitlab_identifier_for_the_model>

   Use the GITLAB_DUO_MODEL environment variable:

   shell

   GITLAB_DUO_MODEL=<gitlab_identifier_for_the_model> glab duo cli

   For example, to use GPT-5-Codex - OpenAI:

   shell

   glab duo cli --model gpt_5_codex

   shell

   GITLAB_DUO_MODEL=gpt_5_codex glab duo cli

   duo

   Use the --model option:

   shell

   duo --model <gitlab_identifier_for_the_model>

   Use the GITLAB_DUO_MODEL environment variable:

   shell

   GITLAB_DUO_MODEL=<gitlab_identifier_for_the_model> duo

   For example, to use GPT-5-Codex - OpenAI:

   shell

   duo --model gpt_5_codex

   shell

   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.

     shell

     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.

     shell

     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