CLI

Background

DoiT provides a command-line interface (CLI) for interacting with the DoiT API directly from your terminal. The dci CLI is a standalone binary that dynamically generates commands from the DoiT API, handles authentication, and supports multiple output formats.

This documentation covers:

Installing the CLI on macOS, Windows, and Linux
Shell completion setup
Authentication via OAuth or API token
Command discovery and usage patterns
Output formats and scripting
A full, generated command reference (available via the sidebar)

Download and install

Install the dci binary using one of the methods below.

macOS (Homebrew)

brew install doitintl/dci-cli/dci

Windows (WinGet)

winget install DoiT.dci

Windows (Scoop)

scoop bucket add doitintl https://github.com/doitintl/dci-cli
scoop install dci

Linux (Debian/Ubuntu)

Download the .deb package from the latest release, then install:

sudo dpkg -i dci_*_linux_amd64.deb

Linux (RHEL/Fedora)

Download the .rpm package from the latest release, then install:

sudo rpm -i dci_*_linux_amd64.rpm

Direct download

Prebuilt binaries for all platforms are available on the GitHub Releases page.

Validate the installation

dci --version

Shell completion

The dci CLI can generate shell completion scripts for tab-completing commands, subcommands, and flags.

Bash

# System-wide (requires sudo):
dci completion bash > /etc/bash_completion.d/dci

# Per-user:
mkdir -p ~/.bash_completions
dci completion bash > ~/.bash_completions/dci
echo 'source ~/.bash_completions/dci' >> ~/.bashrc

Zsh

dci completion zsh > "${fpath[1]}/_dci"

Then restart your shell or run exec zsh to pick up the new completions.

Fish

dci completion fish > ~/.config/fish/completions/dci.fish

PowerShell

dci completion powershell > dci.ps1
# Then add `. /path/to/dci.ps1` to your PowerShell profile.

Completion covers all API commands (list-budgets, list-reports, query, etc.) with descriptions, and includes flag completion for each command. API command completion requires an active auth session (dci login or DCI_API_KEY).

Authentication

The CLI supports two authentication methods.

Interactive (OAuth)

Run dci login to authenticate via the DoiT Console in your browser:

dci login

This opens a browser window, prompts you to log in, completes an OAuth flow, and caches credentials locally. The first time you run any command, the CLI triggers this flow automatically.

To clear cached credentials:

dci logout

API token (CI/automation)

For non-interactive environments such as CI/CD pipelines, cron jobs, and shell scripts, set the DCI_API_KEY environment variable to a DoiT API token:

export DCI_API_KEY=<YOUR_API_TOKEN>

When DCI_API_KEY is set, the CLI uses it instead of OAuth.

Choose a token type

DoiT supports two API token types for programmatic access. For CLI automation, choose based on whether the job runs as you or as shared organizational automation:

Token type	Best for	Where to create it
Personal API token	Scripts or jobs tied to your user	Sign in to the DoiT console. Select your avatar in the upper-right corner of the top navigation bar, and then select your name from the drop-down menu. Select the API tab. Select Create API token.
Service account API token	Shared automation (CI/CD, scheduled jobs) that should not depend on one person	Sign in to the DoiT console, select the gear icon () from the top navigation bar, and then select Users and access. Select Service accounts from the left-hand menu. Select a service account. Select the API tokens tab. Select Create API token.

Use a personal API token for local scripts or one-off automation you run yourself. Use a service account API token for pipelines and scheduled jobs that must keep working if you change roles or leave the organization.

When you create a personal API token, choose a permission scope that matches what the CLI commands need:

Scope	Use when
Read only	The job only reads data (for example, `dci list-reports`)
Full access	The job needs every permission your user role grants
Custom scope	The job needs a specific subset of permissions

Service account tokens inherit the permissions assigned to the service account. Grant only the permissions each workload needs.

Note

New tokens may take up to one minute to work after creation.

Caution

Treat API tokens like passwords. Store DCI_API_KEY in your secrets manager or CI/CD secret store. Do not commit tokens to source control.

For more on creating tokens and permission behavior, see DoiT Developer Hub: Get started, Personal API tokens, and Service accounts.

Verify authentication

Check your current auth method and customer context:

dci status

Getting started

After installing and authenticating, try a few commands:

dci list-budgets
dci list-reports
dci query body.query:"SELECT * FROM aws_cur_2_0 LIMIT 10"

Use --help on any command for inline usage details:

dci --help
dci list-budgets --help

Command structure

Commands are generated directly from the DoiT API. The general structure is:

dci <command> [arguments] [flags]

Examples:

dci list-alerts
dci get-alert <id>
dci list-budgets
dci list-reports

For commands that accept a request body, pass a JSON file with --body:

dci create-alert --body @alert.json

Output formats

Commands support multiple output formats via the --output flag:

Format	Description
`table`	Human-readable tabular display (default)
`json`	Machine-readable JSON — recommended for scripting
`yaml`	YAML structured output
`auto`	Alias for `table`

dci list-budgets --output json
dci list-budgets --output table
dci list-budgets --output yaml

Table output options

When using table output (the default), the following flags control how the table is rendered:

Flag	Short	Default	Description
`--table-mode`	`-M`	`fit`	`fit` truncates long cell values to fit the terminal width. `wrap` wraps them across multiple lines.
`--table-columns`	`-C`	all columns	Comma-separated list of columns to include, in the order listed.
`--table-width`	`-W`	auto-detect	Table width in columns. Defaults to terminal width, falls back to the `COLUMNS` env var, then `120`.
`--table-max-col-width`	`-X`	`0` (auto)	Maximum width per column when fitting or wrapping. `0` lets the CLI decide automatically.

Example combining multiple options:

dci list-budgets --table-mode wrap --table-columns id,name,amount --table-max-col-width 40

Environment variables

Variable	Description
`DCI_API_KEY`	API token for non-interactive authentication (personal or service account)
`DCI_CUSTOMER_CONTEXT`	Override the customer context for commands

Configuration

Configuration is stored in the OS-specific config directory and is created automatically on first run.

OS	Path
macOS	`~/Library/Application Support/dci/apis.json`
Linux	`~/.config/dci/apis.json`
Windows	`%APPDATA%\dci\apis.json`

To reset configuration, delete the file at the path above and re-run dci login.

Using the CLI in scripts

The CLI is suitable for shell scripts, cron jobs, and CI/CD pipelines.

Recommendations:

Use --output json for machine-readable output
Set DCI_API_KEY to a personal or service account API token for non-interactive authentication
Avoid interactive commands in non-TTY environments

Example:

export DCI_API_KEY=<YOUR_API_TOKEN>
budgets=$(dci list-budgets --output json)

Next steps

Browse the CLI command reference in the sidebar
Use --help on any command for inline usage details
Integrate the CLI into scripts and automation using DCI_API_KEY and an API token from the DoiT console

Background​

Download and install​

macOS (Homebrew)​

Windows (WinGet)​

Windows (Scoop)​

Linux (Debian/Ubuntu)​

Linux (RHEL/Fedora)​

Direct download​

Validate the installation​

Shell completion​

Bash​

Zsh​

Fish​

PowerShell​

Authentication​

Interactive (OAuth)​

API token (CI/automation)​

Choose a token type​

Verify authentication​

Getting started​

Command structure​

Output formats​

Table output options​

Environment variables​

Configuration​

Using the CLI in scripts​

Next steps​