# GitLab Duo CLI

GitLab Duo for your command line. An AI-powered CLI tool that brings GitLab Duo's capabilities to your terminal.

## Installation

Install globally using npm:

```shell
npm install -g @gitlab/duo-cli
```

After installation, the CLI can be run using the `duo` command.

### Alternative: Run without installing

You can run the CLI directly without installing it globally:

```shell
npx -y @gitlab/duo-cli
```

### Updating

To update to the latest version:

```shell
npm install -g @gitlab/duo-cli@latest
```

## Usage

### Interactive Mode (TUI)

Start the interactive terminal UI:

```shell
duo
```

On first run, you'll be prompted for a [GitLab authentication token](https://docs.gitlab.com/user/profile/personal_access_tokens/). Your token must have the `api` scope granted.

### Headless Mode

The run command is ideal for non-interactive CI environments or integration with scripts and automated workflows. For example, you can run an eslint command and pipe any errors to Duo: `duo run --goal "Fix these errors: $eslint_output"`

Note that each time you execute `duo run` it will start a fresh workflow, so Duo won't know what the previous conversation or context was.

Run a workflow in non-interactive mode:

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

Additional options for headless mode:

- `--ai-context-items <contextItems>` - JSON encoded array of additional context items
- `--existing-session-id <sessionId>` - Resume an existing session

### Configuration

Edit the CLI configuration:

```shell
duo config edit
```

### Log Management

View and manage logs:

```shell
duo log last              # Open the last log file
duo log list              # List all log files
duo log tail [args...]    # Tail the last log file (supports standard tail arguments)
duo log clear             # Remove all existing log files
```

### Global Options

### Duo command

- `-C, --cwd <path>` - Change working directory
- `--log-level <level>` - Set logging level (debug, info, warn, error)

### Duo run command

- `--gitlab-base-url <url>` - Base URL of GitLab instance (default: `https://gitlab.com`)
- `--gitlab-auth-token <token>` - Authentication token for GitLab instance

### Other options

- `-v, --version` - Display version number
- `--help` - Display help information

#### MCP

Duo CLI supports connecting to local or remote MCP servers using the same MCP configuration as the GitLab IDE extensions. Configuration instructions can be found at [MCP Documentation](https://docs.gitlab.com/user/gitlab_duo/model_context_protocol/mcp_clients/#configure-mcp-servers)

### Environment Variables

You can also configure the CLI using environment variables:

- `GITLAB_URL` or `GITLAB_BASE_URL` - GitLab instance URL
- `GITLAB_TOKEN` or `GITLAB_OAUTH_TOKEN` - Authentication token
- `LOG_LEVEL` - Logging level
- `DUO_WORKFLOW_GIT_HTTP_USER` - Git HTTP authentication username
- `DUO_WORKFLOW_GIT_HTTP_PASSWORD` - Git HTTP authentication password

### Getting Help

Display help for any command:

```shell
duo --help              # Global help
duo run --help          # Help for a specific command
```

## Contributing

See [Development Guide](./docs/development.md) for information on contributing to this project.

## License

See the [License](../../LICENSE) for details.
