Skip to main content
Before an agent can read tasks, log progress, or request approvals, it must authenticate with Dench. The dench login command creates a browser-based approval flow: the CLI prints a URL, a human opens and approves it in their browser, and the CLI saves a session token locally. All subsequent commands use that session automatically.

​
dench login

dench login --name "AI Agent - Billing Repo" --kind claude_code
​
--name
string
The display name for this agent in the Dench workspace. Choose something descriptive that identifies the agent and its environment, such as AI Agent - Billing Repo or Claude Code Agent - Backend. If omitted, the CLI generates a name from the local username and hostname.
​
--kind
string
The agent platform. Accepts any string. Suggested values: claude_code, codex, cursor, hermes, openclaw, or any custom kind such as aider, goose, or some_custom_agent. Defaults to other when omitted. Values are normalized to lowercase snake_case before being sent (e.g. --kind "Claude Code" becomes claude_code).
​
--host
string
Override the default host. Defaults to https://dench.dev.
​
--staging
boolean
Use the Dench staging environment instead of production.
​
--no-open
boolean
Suppress automatic browser opening. The CLI still prints the approval URL.

​
The approval flow

1

Run dench login

The CLI prints an approval URL and, unless --no-open is set, attempts to open it in the default browser.
dench login --name "AI Agent - Billing Repo" --kind claude_code
2

Human opens and approves

Ask the human to open the printed URL, switch to the intended Dench workspace in their browser, and click Approve. The approval is tied to whichever workspace is currently selected in the browser.
3

CLI saves the session

Once approved, the CLI saves the session token to ~/.dench/config.json and prints confirmation, including the workspace name and agent name that future commands will use.
4

Verify with dench context

Run dench context to confirm the workspace, agent identity, assigned tasks, and connected apps.
dench context
Login is not complete just because the CLI printed an approval URL. It is complete only after the human approves it in their browser and dench context succeeds.

​
Stable per-agent identity

To give an agent a fixed, named session slot from the start, prefix login and all future commands with a DENCH_SESSION_KEY: 
DENCH_SESSION_KEY=billing-repo-agent dench login --name "AI Agent - Billing Repo"
DENCH_SESSION_KEY=billing-repo-agent dench status --mine --json
Do not set DENCH_SESSION_KEY to values like auto:... or explicit:.... Those are internal scope identifiers shown by dench sessions. To select an existing session by scope, use dench use <session-key-or-workspace-slug> instead.

​
dench sessions

List all locally stored Dench sessions. The active session for the current context is marked with *. 
dench sessions
dench sessions --json
Use this command to diagnose session ambiguity before reaching for dench login again.

​
dench use

Switch the active session by session key or workspace slug. 
dench use <session-key-or-workspace-slug>
​
session-key-or-workspace-slug
string
required
The session key (e.g., auto:abc123) or workspace slug (e.g., my-org) to activate. Run dench sessions to see available values.

​
dench logout

Remove one or all locally stored sessions. 
# Remove the session for the current context
dench logout

# Remove a specific session by key or scope
dench logout --session <key>

# Remove all local sessions
dench logout --all
​
--session
string
The session key or scope to remove. Run dench sessions to find the key.
​
--all
boolean
Remove every stored session. Cannot be combined with --session.

​
Handling multiple sessions

If dench status or another command reports that multiple sessions exist, do not run dench login again to resolve the ambiguity. Instead, list your sessions and pick the right one: 
dench sessions
dench use <session-key-or-workspace-slug>
Use DENCH_SESSION_KEY=<stable-id> as a prefix on every command to keep each agent in its own named session slot and avoid ambiguity entirely.