Authentication and Profiles

Most CLI confusion comes from one question: “which server, org, workspace, project, and API key is this command actually using?” This page answers that question.

The important model is simple:

• dn login creates or refreshes saved profiles
• command execution resolves one active profile plus any overrides
• scope validation happens right before the CLI actually talks to the platform

The two ways to authenticate

Saved profile

Use dreadnode login to create or update a profile under ~/.dreadnode.

dn login
dn login dn_key_... --server http://localhost:3000
dn login dn_key_... \
  --server https://app.dreadnode.io \
  --profile staging \
  --organization acme \
  --workspace main \
  --project evals

If you omit the API key, the CLI starts the browser-based device login flow and stores a new local API key after the browser flow completes.

Login also resolves and saves your default organization, default workspace, and default project when the platform can provide them. That is why later commands can often omit those flags.

Raw credentials

For one-off commands, you can skip saved profiles entirely:

dn dataset list \
  --server https://app.dreadnode.io \
  --api-key "$DREADNODE_API_KEY" \
  --organization acme \
  --workspace main

This is useful in CI or temporary shells where you do not want to mutate local profile state.

Identity resolution modes

The CLI resolves platform identity in four modes before any network validation happens.

Mode	What happens
--profile <name>	load that saved profile and apply scope overrides
--server <url>	find a matching saved profile by URL and reuse it if possible
--server <url> --api-key <key>	skip saved profiles and use raw credentials directly
no identity flags	use the active saved profile, or fall back to the default platform URL

Note

--server by itself does not always mean “unauthenticated.” If a saved connected profile matches that URL, the CLI will reuse it.

Resolution order

Once the CLI has chosen the base profile, scope values are layered in this order:

1. explicit flags
2. environment variables
3. saved profile defaults

That means --workspace lab beats DREADNODE_WORKSPACE, and DREADNODE_WORKSPACE beats whatever dn login saved last month.

Scope overrides

These are the common scope flags:

• --organization
• --workspace
• --project

They do not replace authentication. They narrow or override the context within the authenticated profile or raw credential session.

dn runtime list --profile staging --workspace lab
dn evaluation list --profile staging --workspace lab --project nightly

During connection, the CLI validates the resulting scope against the platform:

• organization is required for authenticated platform commands
• missing workspaces are auto-resolved to the default workspace when possible
• missing projects are tolerated for some commands, but explicit project-scoped workflows should set --project

Environment variables

Explicit flags win over environment variables, and environment variables win over profile defaults.

Environment variable	Meaning
DREADNODE_SERVER	platform API URL
DREADNODE_API_KEY	platform API key
DREADNODE_ORGANIZATION	default organization
DREADNODE_WORKSPACE	default workspace
DREADNODE_PROJECT	default project

export DREADNODE_SERVER=https://app.dreadnode.io
export DREADNODE_API_KEY=dn_key_...
export DREADNODE_ORGANIZATION=acme
export DREADNODE_WORKSPACE=main
export DREADNODE_PROJECT=nightly

dn evaluation list

The validation rules that matter

• --profile and --server are mutually exclusive.
• --profile and --api-key are mutually exclusive.
• --api-key requires --server.
• a disconnected saved profile cannot be used for authenticated commands.

Those rules are strict and are usually the first thing to check when a command fails before it even reaches the server.

What “disconnected” means

/logout in the TUI, or other local profile cleanup, can leave a saved profile shell behind with no active API key. The CLI treats that as a disconnected profile.

If you see an error saying a saved profile is disconnected, re-authenticate with dn login or switch to raw credentials for that command.

Practical patterns

Use a named profile for repeated daily work

dn login --profile dev --server http://localhost:3000 --organization dreadnode --workspace main
dn capability list --profile dev
dn evaluation list --profile dev

Use raw credentials in CI

dn task sync ./tasks \
  --server https://app.dreadnode.io \
  --api-key "$DREADNODE_API_KEY" \
  --organization acme \
  --workspace main

Use env vars for a temporary shell session

export DREADNODE_SERVER=http://localhost:3000
export DREADNODE_API_KEY=dn_key_...
export DREADNODE_ORGANIZATION=dreadnode
export DREADNODE_WORKSPACE=main

dn sandbox list

One naming distinction to remember

--server means the platform API URL.

When the default app command connects to a runtime host, it uses --runtime-server instead. That is a different concept. See /cli/launch-and-runtime/.