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.

When you start a new session, the prompt placeholder might show a tip about a GitLab Duo CLI feature.

Startup cards

Startup cards appear in your terminal when you start a new session in interactive mode: an onboarding card on your first run, and a welcome card on later runs. The cards do not appear when you resume an existing session.

Startup cards are enabled by default, but you can turn them off.

Onboarding card

The first time you run the GitLab Duo CLI on a machine, an onboarding card helps you connect MCP servers and install plugins from the GitLab marketplace.

The card displays navigation hints to select and run the steps. Completed steps show a checkmark with the number of connected MCP servers or installed plugins.

The card stays until you send your first prompt, even after you complete both steps. It does not appear again on later runs.

Welcome card

Every time you start a new session, a welcome card appears by default. You can turn off the card with the Show work items on session start setting.

The card suggests prompts to kick off common tasks and displays navigation hints for browsing and running prompts. For example, when you work in a GitLab project, the suggested prompts are built from your open merge requests and issues. Otherwise, the card shows generic examples.

When you select a prompt for one of your merge requests and its source branch exists, the prompt tells GitLab Duo to check out that branch first.

If the Run suggested prompts as /goal sessions setting is enabled and your instance is GitLab 19.3 or later, the prompt to address review feedback runs as a /goal session.

Hide the startup cards

Startup cards are enabled by default. To turn them off, set --startup-cards to false:

glab duo cli --startup-cards false

duo --startup-cards false

Alternatively, set the STARTUP_CARDS environment variable to false. If you set both, the --startup-cards option takes precedence over the environment variable.

Status bar

The bottom of the screen shows a status bar with:

• The current working directory and Git branch.
• The detected GitLab project and, if one exists, the open merge request for the current branch and its pipeline status.
• The progress of a running /goal session.
• The status of configured MCP servers.

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:

To close a panel or dialog that a slash command opens, press Escape.

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

Settings

To view and change settings, type /settings in interactive mode. For more information, see GitLab Duo CLI settings.

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 instance, group, or project before you can use it. Groups inherit the setting from the instance, and 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.

Provide images as context

In interactive and headless mode, GitLab Duo can read images and use them as context. You cannot attach an image to your prompt. Instead, in your prompt, name an image file in the repository or an image attached to an issue or merge request in the same project.

For more information about how to reference images and the image requirements, see provide images as context. For example prompts, see use images as context.

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