Install and sign in

Install the duun CLI, sign in with the browser or an API key, manage profiles and environment variables, and run it in CI.

On this page

The duun command-line tool starts and follows runs, keeps workflows in version control, and publishes skills, all from your terminal or CI. It talks to the Duun API, so anything it does respects the same scopes, limits and approvals as the app.

Install

The CLI needs Node.js 22 or later.

npm install -g @duun/cli
pnpm add -g @duun/cli

Check the install:

duun --version
duun 0.9.2 (api 2026-11-01)

To update, run the same install command again. To remove it, use npm uninstall -g @duun/cli or pnpm remove -g @duun/cli.

Sign in

On your own machine, sign in with the browser:

duun login
Opening https://app.duun.ai/device in your browser…
Confirm this code matches: QKMT-4829

✓ Signed in to acme as alex@acme.dev
  Key saved to profile "default" (scopes: runs, factories, workflows, skills, commands)

duun login uses a device flow: the CLI shows a code, you confirm it in the browser, and Duun creates an API key for the CLI with the scopes you approve. The key is stored in your config file and appears in Settings → API keys & secrets → Duun API keys as CLI · <your machine name>, where you can revoke it.

Check who you are signed in as at any time:

duun whoami
alex@acme.dev on acme (ws_acme)
Profile: default · Key: duun_sk_…f81c · Scopes: runs:read runs:write factories:read workflows:read workflows:write skills:write

duun logout deletes the key from your config file and revokes it.

Sign in with an API key

For CI, servers and anywhere without a browser, create a key in Settings → API keys & secrets → Duun API keys → New API key (Admins only), give it only the scopes the job needs, and pass it with --token:

duun login --token "$DUUN_API_KEY"

You can also skip login and set the DUUN_API_KEY environment variable. The CLI reads it on every command, which is usually simpler in CI. See API overview for the scope list.

Profiles and the config file

The CLI keeps its settings in ~/.config/duun/config.toml (or $XDG_CONFIG_HOME/duun/config.toml). Each profile holds a workspace and a key, so you can switch between workspaces without signing in again.

~/.config/duun/config.toml
default_profile = "default"

[profiles.default]
workspace = "acme"
api_key = "duun_sk_live_…f81c"

[profiles.sandbox]
workspace = "acme-sandbox"
api_key = "duun_sk_live_…09ad"
output = "json"

Sign in to a second profile with duun login --profile sandbox, then pick it per command:

duun runs list --profile sandbox
KeyDescription
default_profileProfile used when you don’t pass --profile.
workspaceWorkspace slug, as in app.duun.ai/acme.
api_keyThe key written by duun login.
outputtext (default) or json. Same as passing --json.
api_urlOverride the API base URL. You won’t need this unless Duun support asks.

The config file is created with permissions 0600. Don’t commit it.

Environment variables

Environment variables override the config file, and flags override both.

VariableDescription
DUUN_API_KEYAPI key to use. Takes precedence over the profile’s key.
DUUN_WORKSPACEWorkspace slug. Same as --workspace.
DUUN_API_URLAPI base URL. Defaults to https://api.duun.ai/v1.
NO_COLORSet to any value to turn off colour in output.

Global flags

Every command accepts these flags.

FlagDescription
--workspace <slug>Run against another workspace.
--profile <name>Use a profile from the config file.
--jsonPrint machine-readable JSON instead of text. Errors are printed as JSON on stderr.
--helpShow help for the command.
--versionPrint the CLI and API versions.

Use the CLI in CI

A common setup keeps workflows in the repository as YAML files and applies them when they change on the main branch. Pull requests get a diff so reviewers can see what will change. See Command reference for the file format.

.github/workflows/duun-workflows.yml
name: Duun workflows

on:
  pull_request:
    paths: ["duun/workflows/**"]
  push:
    branches: [main]
    paths: ["duun/workflows/**"]

jobs:
  workflows:
    runs-on: ubuntu-latest
    env:
      DUUN_API_KEY: ${{ secrets.DUUN_API_KEY }}
      DUUN_WORKSPACE: acme
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install -g @duun/cli

      - name: Diff workflows
        if: github.event_name == 'pull_request'
        run: |
          for f in duun/workflows/*.yaml; do
            duun workflows diff "$f"
          done

      - name: Apply workflows
        if: github.event_name == 'push'
        run: |
          for f in duun/workflows/*.yaml; do
            duun workflows apply "$f" --yes --message "Applied from ${GITHUB_SHA::7}"
          done

duun workflows diff exits with code 3 when the file has problems (for example a reference to a step that doesn’t run first), so the pull request check fails before anything is applied. apply refuses to overwrite a version someone applied in the app after your file was pulled; pull again and resolve the change. The key for this job needs workflows:read and workflows:write.

Shell completion

Generate a completion script for your shell and load it from your shell’s startup file.

# zsh
duun completion zsh > "${fpath[1]}/_duun"

# bash
duun completion bash > ~/.local/share/bash-completion/completions/duun

# fish
duun completion fish > ~/.config/fish/completions/duun.fish

Completion covers commands, flags, and live values such as factory ids, workflow ids and run ids from your workspace.

Next steps

    Type to search the docs, help center and blog.