Dench CLI

Agent-facing CLI for the Dench agent workspace.

Usage

Run without installing. The npm package is @dench.com/cli, but the binary it installs is named dench, so always invoke it as npx -y -p @dench.com/cli dench <command>. A bare npx -y @dench.com/cli <command> will fail because npx looks for a bin matching the package's last path segment (cli) and there isn't one.

npx -y -p @dench.com/cli dench signin --name "AI Agent - Billing Repo"

Or install globally:

npm install -g @dench.com/cli
dench signin --name "AI Agent - Billing Repo"

--kind 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 send (e.g. --kind "Claude Code" becomes claude_code).

The default backend is https://dench.com (production). Use dench backend to switch:

dench backend show
dench backend set production
dench backend set staging
dench backend set local                  # http://localhost:3000
dench backend set https://example.com    # custom URL
dench backend clear                      # revert to production

For one-shot overrides (no config change):

dench --prod <cmd>
dench --staging <cmd>
dench --backend local <cmd>
dench --host https://example.com <cmd>
DENCH_HOST=https://example.com dench <cmd>

The smooth setup flow is:

1. Run dench signin --name "AI Agent - Billing Repo" once.
2. Let the CLI open the approval link. If it cannot, ask the human to open the printed link and confirm the email/workspace. Use --no-open to print the link without opening it.
3. Run dench status --mine --json and dench crm entries list task --json to verify setup. Tasks live as CRM task entries — there is no separate dench tasks command.

The CLI selects the approved session for later commands automatically. Setup is complete after approval, both verification commands work, and you know which Dench agent/session is selected.

Approval happens in the human's browser and uses the currently selected Dench workspace. The human should switch to the intended workspace before approving. The CLI opens the approval link automatically when possible. If opening fails, use the printed link manually.

If multiple sessions already exist, do not log in again to fix ambiguity and do not silently guess from the newest timestamp, agent name, or kind. List sessions and ask the human which exact session to use:

dench sessions
dench use <session-key-or-workspace-slug>

Use a human-readable DENCH_SESSION_KEY at sign-in time only for long-lived agents or when the human asks for a stable identity:

DENCH_SESSION_KEY=billing-repo-agent dench signin --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 scopes shown by dench sessions; select them with dench use <session-key-or-workspace-slug> instead.

dench logout removes only the current selected session for this local agent context. Other saved sessions can still be reused by future chats. To remove the wrong local session, run dench logout --session <session-key>. Use dench logout --all only when you want to clear every local Dench session.

Do not create or edit local agent memory files during setup. Use Dench memory only when the human asks or when saving a stable workspace fact.

Tasks live as CRM task entries — there is no separate dench tasks, dench task, dench claim, or dench log command. Create one via dench crm entries create task --data '{"Name":"…","Status":"To Do"}' only when the human assigns durable work or coordination benefits from a tracked entry (confirm field names with dench crm fields list task first — unknown fields are rejected). For ad-hoc requests, work directly.

Use dench context when you need to know who you are, which workspace you are using, pending approvals you requested, connected apps, and the best next commands. Add --json for structured output.

Past chat threads

Browse and search the user's past chat threads in this workspace (own + shared). Useful for pulling in earlier context when the user refers to something they discussed before. The chat agent has the equivalent in-process tools (list_past_chats, search_past_chats, read_past_chat); this CLI surface is the same data accessed via bash.

dench chat list [--query <substr>] [--limit N] [--include-archived] [--json]
dench chat search "<query>" [--limit N] [--json]
dench chat read <thread-id> [--limit N] [--json]

Visibility scope: only threads created by the current user, plus threads in the same organization marked as shared.

dench chat search is a keyword full-text search across past message text — pick concrete tokens that the prior chat would have used (file paths, product names, error strings) rather than paraphrases.

Inside a sandbox, dench chat uses DENCH_API_KEY + DENCH_RUN_ID automatically; locally, run dench signin first.

Billing

Fresh workspaces verify a card for abuse prevention before starter credits are issued. The card verification does not charge the human. New workspaces receive $5 in starter AI credits, with automatic overage disabled by default.

Check AI credits:

dench billing status --json

Create a top-up link for the human to pay:

dench billing topup --amount 5 --json

Do not claim the top-up succeeded until Stripe returns success or dench billing status --json shows the new credits.

External Apps

List connected apps:

dench integrations --json

dench integrations is an alias for dench tool status with no toolkit.

Other tool commands:

dench tool status [toolkit] --json
dench tool connect <toolkit> --json
dench tool search "list recent gmail emails" --toolkit gmail
dench tool run <composio_tool_slug> --args '{"key":"value"}' --json

Start with compact dench tool search output. It lists ranked tools with slug, toolkit, connection status, and read-only/approval hints. Add --json only when you need full raw schemas or exact argument details.

Run clear read-only information retrieval tools through Dench without requesting manual approval first. This includes slugs containing FETCH, GET, LIST, SEARCH, READ, or FIND, such as GMAIL_FETCH_EMAILS:

dench tool run GMAIL_FETCH_EMAILS --args '{"max_results":10}' --json

Dench enforces the final policy and returns requiresApproval when approval is needed.

For Gmail and other email tools, summarize safely. Prefer metadata and snippets. Do not repeat OTP codes, security codes, passwords, tokens, API keys, or secrets from email bodies. Non-JSON tool run display redacts likely sensitive codes; --json preserves the raw provider response for cases that need it.

Run dench tool --help or dench integrations --help for command help.

For staging:

dench signin --staging
dench signin --host https://workspace-staging.dench.com

Sandbox / API key auth (no dench signin required)

Inside a Daytona sandbox the unified Dench API key is baked into envVars at create time (see src/lib/secrets/sandbox-tokens.ts). When DENCH_API_KEY and CONVEX_URL are both present, the CLI skips the dench signin flow entirely and uses the API key as a bearer for every org-scoped command — dench crm, dench files, dench fs sync, etc.

export DENCH_API_KEY=dench_pk_live_…
export CONVEX_URL=https://your-convex-deployment.convex.cloud
# Optional but enables nicer URLs in CLI output:
export DENCH_API_URL=https://app.dench.com
export DENCH_ORG_ID=…
export DENCH_ORG_SLUG=…

dench crm entries list people

Auth precedence:

1. Explicit --dev flag → use the dev workspace env (NEXT_PUBLIC_CONVEX_URL, DENCH_WORKSPACE, DENCH_DEV_AGENT_KEY).
2. A locally-stored dench signin session for the current backend (set via dench backend, --host, --prod, or --staging).
3. DENCH_API_KEY + CONVEX_URL (sandbox / automation path).

Plain terminal usage does not silently fall back to dev env vars. Without --dev, a saved session, or DENCH_API_KEY + CONVEX_URL, live commands return login_required.

.env auto-load is opt-in

When dench runs from inside the dench.com repo it does not auto-load workspace .env / .env.local files by default — that used to silently flip NEXT_PUBLIC_CONVEX_URL to the dev Convex deployment and made the CLI talk to local Convex even when the user expected production.

Auto-load now turns on only when one of:

• --dev (also switches the runtime to dev-workspace mode)
• --use-dev-env (load .env files but keep the rest of the runtime)
• DENCH_USE_DEV_ENV=1 in the shell env (e.g. via direnv)
• dench backend set local (a stored local backend implies dev env)

Explicit shell exports (GATEWAY_URL=… ./dench …) always win regardless.

Commands that need to impersonate a specific agent (dench memory, dench approval request, etc.) still require an agent session (dench signin) — the unified API key is org-scoped and cannot speak as a single agent. Those commands return a clear "agent session required" error in API-key mode.