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/clipnpm add -g @duun/cliCheck the install:
duun --versionduun 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 loginOpening 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 whoamialex@acme.dev on acme (ws_acme)
Profile: default · Key: duun_sk_…f81c · Scopes: runs:read runs:write factories:read workflows:read workflows:write skills:writeduun 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.
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| Key | Description |
|---|---|
default_profile | Profile used when you don’t pass --profile. |
workspace | Workspace slug, as in app.duun.ai/acme. |
api_key | The key written by duun login. |
output | text (default) or json. Same as passing --json. |
api_url | Override 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.
| Variable | Description |
|---|---|
DUUN_API_KEY | API key to use. Takes precedence over the profile’s key. |
DUUN_WORKSPACE | Workspace slug. Same as --workspace. |
DUUN_API_URL | API base URL. Defaults to https://api.duun.ai/v1. |
NO_COLOR | Set to any value to turn off colour in output. |
Global flags
Every command accepts these flags.
| Flag | Description |
|---|---|
--workspace <slug> | Run against another workspace. |
--profile <name> | Use a profile from the config file. |
--json | Print machine-readable JSON instead of text. Errors are printed as JSON on stderr. |
--help | Show help for the command. |
--version | Print 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.
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}"
doneduun 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.fishCompletion covers commands, flags, and live values such as factory ids, workflow ids and run ids from your workspace.