GitLab Duo CLI (duo)

  • Tier: Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
  • Status: Experiment

The GitLab Duo CLI is a command-line interface tool that brings GitLab Duo Chat (agentic) to your terminal. Available for use with any operating system and editor, use duo to ask complex questions about your codebase and to autonomously perform actions on your behalf.

The GitLab Duo CLI can help you:

  • Understand your codebase structure, cross-file functionality, and individual code snippets.
  • Build, modify, refactor, and modernize code.
  • Troubleshoot errors and fix code issues.
  • Automate CI/CD configuration, troubleshoot pipeline errors, and optimize pipelines.
  • Perform multi-step development tasks autonomously.

The GitLab Duo CLI offers two modes:

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

Prerequisites

Set up the GitLab Duo CLI

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.

With the GitLab CLI

Prerequisites:

To set up the GitLab Duo CLI for use through the GitLab CLI:

  1. Run the glab command for the GitLab Duo CLI:

    glab duo cli

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

Without the GitLab CLI

To use the GitLab Duo CLI as a standalone tool, install it and then authenticate.

Install

Install the GitLab Duo CLI as an npm package or compiled binary.

Prerequisites:

  • Node.js 22 or later.
  • For GitLab Self-Managed with a self-signed certificate, either:
    • Node.js LTS 22.20.0 or later
    • Node.js 23.8.0 or later

To install the GitLab Duo CLI as an npm package, run:

npm install --global @gitlab/duo-cli

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

Authenticate

If glab is already installed and authenticated on your system when you first run duo, duo automatically uses glab as a credential helper. You do not need to authenticate separately. This requires glab 1.85.2 or later and duo 8.68.0 or later.

If you authenticated duo before this feature was available and want to use glab as a credential helper instead, delete your authentication settings from ~/.gitlab/storage.json.

Prerequisites:

To authenticate:

  1. Run duo in your terminal. The first time you run the GitLab Duo CLI, a configuration screen appears.
  2. Enter a GitLab Instance URL and then press Enter:
    • For GitLab.com, enter https://gitlab.com.
    • For GitLab Self-Managed or GitLab Dedicated, enter your instance URL.
  3. For GitLab Token, enter your personal access token.
  4. To save and exit the CLI, press Enter.
  5. To restart the CLI, run duo in your terminal.

To modify the configuration after initial setup, use duo config edit.

Authenticate with environment variables

Prerequisites:

To authenticate with environment variables:

  1. Set GITLAB_TOKEN or GITLAB_OAUTH_TOKEN to your personal access token.

    export GITLAB_TOKEN="<your-personal-access-token>"

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

Use the GitLab Duo CLI

Prerequisites:

Interactive mode

To use the GitLab Duo CLI in interactive mode:

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

    glab duo cli
    duo

  2. The prompt Duo 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.

Headless mode

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:

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"

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"

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.

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.

Options

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.
  • --model <model>: Select the AI model to use for your 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).

Commands

The following commands are available for each setup:

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

Environment variables

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_OAUTH_TOKEN or GITLAB_TOKEN: Authentication token.
  • LOG_LEVEL: Logging level.

Proxy and custom certificate configuration

If your network uses an HTTPS-intercepting proxy or requires custom SSL certificates, you might need additional configuration.

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

Custom SSL certificates

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

    • 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

Ignore certificate errors

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

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:

  • 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

Update the GitLab Duo CLI

To manually update the GitLab Duo CLI to the latest version, run the command for your setup:

glab duo cli --update
npm install --global @gitlab/duo-cli@latest

Contribute to the GitLab Duo CLI

For information on contributing to the GitLab Duo CLI, see the development guide.