Skip to main content

Documentation Index

Fetch the complete documentation index at: https://dench.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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 in ~/.dench/config.json. For first-time setup, prefer dench onboard. Use dench login directly when you only need authentication or session repair.

​
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 https://workspace-staging.dench.com instead of production.
​
--prod
boolean
Force the production host, https://dench.dev.
​
--no-open
boolean
Suppress automatic browser opening. The CLI still prints the approval URL.
​
--timeout-ms
number
How long the CLI should wait for browser approval before timing out. Defaults to 15 minutes.
​
--session-key
string
Stable human-readable session identity. This has the same purpose as DENCH_SESSION_KEY. Do not pass internal values that start with auto: or explicit:.
Omit --json for interactive dench login. The approval URL is human-facing setup output, so use normal text mode while the human approves the browser link. Add --json to verification commands after login succeeds.

​
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 DENCH_SESSION_KEY, or pass --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

dench login --session-key billing-repo-agent --name "AI Agent - Billing Repo"
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 local context is marked with *. 
dench sessions
dench sessions --json
Use this command to diagnose session ambiguity before reaching for dench login again. The JSON output includes each session key, host, workspace, agent, scope, saved time, expiration time, and whether it is current.

​
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, session scope, workspace slug, workspace name, workspace ID, agent ID, or agent name to activate. Run dench sessions to see available values. If more than one session matches, rerun with the exact session key.

​
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.

​
Session selection rules

Dench stores sessions per host and local context. The CLI tries the following, in order:
  1. A current session selected for the current local context.
  2. A default current session for the host, unless you are using an explicit stable session key.
  3. The exact session key for the current host and local context.
  4. A legacy host-only session, if it is the only saved session for that host.
If more than one saved session could match, the CLI returns session_ambiguous and tells you to run dench sessions --json and dench use <session-key-or-workspace-slug>.