Command-line reference
Every den command and its flags, generated from the commands themselves, so it
matches den --help of this version. Run with no command, den opens the dashboard;
den --version prints the version and den COMMAND --help the text below.
Without -c den reads ./den.yaml, then ~/.config/den/den.yaml; with it, the file must
exist. The keys of the file are in the configuration reference.
den
Developer connectivity tool — RDS, Redis, DocumentDB, Redshift, OpenSearch, Neptune, Docker
den opens tunnels, manages IAM tokens, and provides a TUI for all your dev services.
denFlags:
-c, --config string config file (default: ./den.yaml, then den.yaml in the config directory; see den paths)den config
Show resolved config, or check it with –check
Shows den.yaml as den reads it: environments merged in, defaults filled.
With --check, checks the file instead and prints every problem with its line and a hint on how to fix it: mistakes den cannot run with (errors), and things it runs without but you probably did not mean (warnings): unknown keys, files that are not there, local ports two services share, unknown AWS profiles, duplicate names. FILE checks that file instead of the one den finds. The exit code is 1 when there are errors, and with --strict when there are warnings too, so a pipeline can run it.
den config [FILE] [flags]Flags:
--check check the file and print its problems instead of the config
--json print JSON
--strict with --check, exit 1 on warnings tooden connect
Open the dashboard with a configured service connecting
Open the dashboard and connect the service den.yaml calls NAME, as if you had selected it and pressed c. den list shows the names.
den connect NAMEden create-env
Start docker compose environment
den create-env [flags]Guide: docs/docker
Flags:
-f, --file string docker-compose file (default: docker-compose.yml)den doctor
Check what den needs and say how to install what is missing
Check what den needs outside itself and say how to fix what is missing: the config, the AWS CLI and Session Manager plugin, the AWS profiles den.yaml names, SSO logins, local ports, and the client tools the services and secrets use: where each is installed, its version, and the install, upgrade or PATH command for this OS and package manager. den prints these commands; it never runs them. Exits 1 when a check fails.
--for checks only what the named features need, with or without a config: den doctor --for sops before writing den.yaml, or in an onboarding script. Features: aws, aws_secretsmanager, claude, codex, docker, documentdb, eice, keepassxc, kubectl, mysql, neptune, opensearch, rds, redis, redshift, runbook-sources, sops, ssh, ssm, tui, tunnel, vault, vpn, all. Tunnelled services (rds, redis, …) assume the ssm transport unless ssh, eice or kubectl is named too.
--os shows the install steps for another platform (macos, debian, fedora, windows, optionally /amd64 or /arm64) without checking this machine, for the features named by --for or, without it, for everything den.yaml uses.
--deep also asks AWS whether each bastion’s SSM agent is online (read-only, uses your AWS credentials).
--explain asks Claude to explain the problems in plain language. den first prints exactly what it would send — names, hosts, IDs and paths replaced by placeholders — and sends it only if you agree (or pass --yes). The answer comes back with your real names restored locally. Needs ANTHROPIC_API_KEY or ant auth login.
den doctor [flags]Also called check-install.
Guide: docs/doctor
Examples:
den doctor
den check-install --for sops
den doctor --for rds,redis --json
den doctor --for sops,vault --os windowsFlags:
--deep also check each bastion is online in SSM (calls AWS)
--explain ask Claude to explain the problems (shows what it sends first)
--for strings check only what these features need (comma-separated; see above)
--json print JSON
--os string show the install steps for another platform instead of checking this one
--yes with --explain, send without askingden init
Write a starter den.yaml from what an AWS account has
List the SSM-managed instances and the private data stores (RDS and Aurora, ElastiCache, MemoryDB, DocumentDB, Redshift, OpenSearch, Neptune) that one AWS profile can see in one region, and write a den.yaml that reaches them through one of those instances. Read-only: it only calls Describe and List APIs.
The result is a normal static config to review and edit; den never discovers at run time.
den init [flags]Guide: docs/init
Examples:
den init --profile dev --region eu-central-1
den init --profile dev -o ~/.config/den/den.yaml
den init --profile dev --bastion i-0123456789abcdef0 --env dev -o den.yamlFlags:
--bastion string instance ID of the SSM-managed instance to tunnel through
--env string name of the generated environment (default: the region)
--force overwrite the output file if it exists
-o, --output string file to write, or - for stdout (default "-")
--profile string AWS profile to look with, and to put in the config (default $AWS_PROFILE)
--region string AWS region (default: the profile's)den list
List services from config
List the services den.yaml defines. The status is this process’s own view, so it is idle: live connections belong to the TUI (or den mcp) that opened them.
den list [flags]Flags:
--json print JSONden mcp
Serve den to AI agents over the Model Context Protocol (stdio)
Run an MCP server on stdin/stdout so an AI agent (Claude Code, Cursor, …) can list den’s services, open a tunnel and read its status and logs — and, when den.yaml’s mcp.allow_runbooks is on, run runbooks.
Credentials are never returned to the agent. Production services are refused unless mcp.allow_production is on, and then need your confirmation in the MCP client for each connect. Tunnels the agent opens close when it disconnects.
Register it with Claude Code: claude mcp add den -- den mcp -c ~/.config/den/den.yaml
den mcpGuide: docs/mcp
den paths
List the files and folders den reads and writes on this machine
Print every file and folder den uses here, and whether each exists: the den.yaml in use and why that one, the config directory your own files belong in, the runbook folders, the VPN settings files, and where den keeps its state and downloaded data.
Like go env, it only reports; it never creates or changes anything. The folders follow XDG_CONFIG_HOME, XDG_STATE_HOME and XDG_DATA_HOME, and APPDATA and LOCALAPPDATA on Windows.
den paths [flags]Flags:
--json print the paths as JSONden run
Run a runbook (one of your scripts, with den’s AWS context) or sequence
Run a runbook or sequence defined in den.yaml or discovered in a scanned directory. Exits with the script’s own exit code.
DEN_PORT_* variables reflect live connections and are only available inside the TUI; a standalone den run exports none.
den run [name] [flags]Guide: docs/runbooks
Flags:
--json with --list, print JSON
--list list runbooks and sequences
--param stringArray parameter as key=value (repeatable)
--yes skip the confirmation promptden runbook
Your scripts, run with den’s AWS profile, region and tunnels: manage runbook folders
den runbookGuide: docs/runbooks
den runbook browse
List every runbook in a source, installed or not
den runbook browse <source> [flags]Guide: docs/runbooks
Flags:
--json print JSONden runbook delete
Delete a runbook or sequence for good, with its runs and its state folder
Delete a runbook or a sequence for good: its folder, script or den.yaml entry, the runs den kept, its DEN_RUNBOOK_STATE folder and, for a runbook from a source, the record of your review. A runbook from a source is uninstalled: its checkout is shared with the source’s other runbooks. A running one is refused. It asks first at a terminal; elsewhere it needs --yes.
den runbook delete <name> [flags]Also called rm.
Guide: docs/runbooks
Flags:
--yes skip the confirmation promptden runbook fork
Copy a source’s runbook into your runbooks folder, to change it
Copy the folder of a runbook from a source into the first of runbooks.dirs, or --dir, as a runbook of your own: you can change it, and updates of the source leave it alone. Its env: is set to the environment env_map gave it.
den runbook fork <source>/<runbook> [flags]Guide: docs/runbooks
Flags:
--dir string directory to copy it into (default: the first of runbooks.dirs)den runbook install
Show a runbook of a source: edits its include/exclude in den.yaml
den runbook install <source>/<runbook>Guide: docs/runbooks
den runbook migrate
Move a runbook defined by a # den: header script into a folder of its own
Move a runbook that is a single script with a # den: header into a folder of its own next to it: runbook.yaml from the header, the script as run<ext> without the den: lines, and README.md from its comment block. --all moves every one. It asks first at a terminal; elsewhere it needs --yes.
den runbook migrate [name] [flags]Guide: docs/runbooks
Flags:
--all move every runbook still defined by a header script
--yes skip the confirmation promptden runbook new
Create a runbook folder, and have an agent write it if you like
Create a folder for a new runbook in the first of runbooks.dirs, or in --dir, from runbooks.template when den.yaml sets one, else from den’s own template: a runbook.yaml naming every key it may set, a run.sh and a README.md.
With --agent (or a description of what it should do), den then starts Claude Code or Codex in the folder, with den’s MCP server and its runbook guide, to write it. The session is yours: the agent asks before it writes or runs anything.
den runbook new "RDS status" "check my RDS instances in eu-staging, in Rust" --agent claudeden runbook new <name> [what it should do] [flags]Guide: docs/runbooks/agents/cli
Flags:
--agent string have an agent write it: claude, codex, auto or a runbooks.agents name (default: runbooks.agent, else auto)
--dir string directory to create the folder in (default: the first of runbooks.dirs)den runbook source
Git repositories of runbooks: add, list, update, sync, remove
A runbook source is a git repository of runbook folders, named in den.yaml’s runbooks.sources. den checks it out at the commit den.lock pins and lists its runbooks as <source>/<name>. Nothing updates on its own: update moves a source to the newest commit of its ref, and a runbook it added or changed asks before its next run.
den runbook sourceGuide: docs/runbook-sources
den runbook source add
Add a git repository of runbooks to den.yaml and check it out
Add a runbook source to runbooks.sources in den.yaml, keeping the rest of the file as written, then check it out and pin it in den.lock beside den.yaml.
den runbook source add git@ghe.acme.com:ops/den-runbooks.git --ref v1.4.0 \
--path runbooks --env-map prod=eu-prodThe URL may be https://, ssh://, git@host:owner/repo, host/owner/repo or owner/repo on GitHub. Credentials come from git (a credential helper or your SSH key), never from the URL.
den runbook source add <url> [flags]Guide: docs/runbook-sources
Flags:
--env-map stringArray map an env its runbooks use to one of yours, as theirs=yours (repeatable)
--name string the source's name, prefixing its runbooks (default: from the URL)
--no-fetch only write den.yaml; check it out later with den runbook source update
--path string folder of the repository holding the runbook folders (default: its root)
--ref string tag, branch or commit to check out (default: the repository's default branch)den runbook source list
List the runbook sources, where each is checked out and what it holds
den runbook source list [flags]Guide: docs/runbook-sources
Flags:
--json print JSONden runbook source remove
Remove a runbook source from den.yaml and den.lock and delete its checkout
den runbook source remove <name> [flags]Guide: docs/runbook-sources
Flags:
--yes skip the confirmation promptden runbook source sync
Check out the commits den.lock pins, as after pulling a shared config
den runbook source syncGuide: docs/runbook-sources
den runbook source update
Fetch sources and move them to the newest commit of their ref
Fetch each named source, or every one, check out the newest commit of its ref and pin it in den.lock. A tag or a commit stays put; a branch moves. Runbooks the update added or changed ask before their next run.
den runbook source update [name...]Guide: docs/runbook-sources
den runbook uninstall
Hide a runbook of a source: edits its include/exclude in den.yaml
den runbook uninstall <source>/<runbook>Guide: docs/runbooks
den schema
Print the JSON Schema for den.yaml
Print the JSON Schema for den.yaml. Point your editor’s YAML language server at it for completion and validation:
den schema > ~/.config/den/den.schema.json
# first line of den.yaml:
# yaml-language-server: $schema=den.schema.jsonden schemaGuide: docs/schema
den vpn
Manage the VPN privilege helper
Manage the helper that lets den bring the VPN up and down without an admin prompt. Without it, openfortivpn needs root and den falls back to the system’s admin dialog on every connect and disconnect.
den vpnGuide: docs/vpn
den vpn install-helper
Install the root-owned VPN helper and its sudoers rule
Install a root-owned helper plus a sudoers rule pinned to it, so den can start and stop the VPN without asking for your password.
Everything that will be written is printed first. You are asked for your password once, by sudo, in this terminal.
Re-run this after changing a vpn: entry in den.yaml — the helper runs the copy of the settings made here, not the file in your config.
den vpn install-helper [flags]Guide: docs/vpn
Flags:
--name string only install this VPN entry (default: every vpn: entry)
-y, --yes skip the confirmation promptden vpn status
Show whether the VPN helper is installed and usable
den vpn statusGuide: docs/vpn
den vpn uninstall-helper
Remove the VPN helper and its sudoers rule
den vpn uninstall-helper [flags]Guide: docs/vpn
Flags:
-y, --yes skip the confirmation prompt