Using the Dosu CLI

The Dosu CLI (dosu) gives agents and users full access to the Dosu platform from the terminal. Every command supports --json for structured output and --help for parameter details.

When to use this skill

Activate when the user wants to:

Search or query their organization's knowledge base
Create, edit, review, or publish documentation
Manage conversation threads from GitHub/Slack
Check usage analytics or team activity
Manage team members, data sources, or integrations
Perform any action they'd normally do in the Dosu web dashboard

Prerequisites

Step 0 — Verify the Dosu CLI is installed

Before running anything else, check that dosu is on the PATH:

dosu --version

If dosu is not found, ask the user one question and stop:

Dosu CLI isn't installed on this machine. Want me to install it for you? Pick one:

npm (cross-platform, needs Node 18+): npm install -g @dosu/cli

Homebrew (macOS/Linux, cleanest — no Gatekeeper prompt): brew install dosu-ai/dosu/dosu

curl (macOS/Linux without Node): curl -fsSL https://raw.githubusercontent.com/dosu-ai/dosu-cli/main/install.sh | sh

After the user picks one and confirms, run that exact command, then re-run dosu --version to verify before continuing.

Do NOT use npx @dosu/cli as a workaround — it runs the CLI once but does not install the dosu command. The skill's commands (dosu ask, dosu docs, etc.) require dosu to be on the PATH.

Do NOT pre-emptively run which dosu, npm ls -g, brew list, ls /usr/local/bin/dosu, etc. — dosu --version is the only check you need.

Step 1 — Authenticate

Once the CLI is installed, the split auth model:

dosu login    # Browser OAuth → saves access token for JWT-authenticated tRPC commands
dosu setup    # Interactive: select org → deployment → create API key → configure tools
dosu status   # Verify: shows login state, deployment, and mode

dosu login is required for all tRPC-backed commands. It saves a Supabase access token used to authenticate requests via Supabase-Access-Token.
dosu setup is required whenever a command needs deployment/space selection or an API key. In practice, that means ask, plus the backend-backed document actions docs generate, docs auto-tag, and docs publish.
For full CLI capability, agents should usually run both dosu login and dosu setup before starting work.

If a command fails with "Not logged in", run dosu login. If it fails with "API key not configured" or "Run 'dosu setup'", run dosu setup.

Key concepts

Understanding Dosu's domain model helps choose the right commands:

Organization — the top-level account. Users belong to one or more orgs.
Deployment — an instance of Dosu within an org. Each has its own knowledge base and configuration.
Space — the container for a deployment's content (threads, pages, analytics).
Knowledge Store — the indexed collection of all connected data. Lives within a space.
Data Source — a connection to an external platform (GitHub repo, Slack workspace, Confluence space, Notion workspace, Coda doc). Data is synced from sources into the knowledge store.
Page/Document — a unit of documentation. Can be created manually, generated by AI, or imported from a data source.
Tag — a topic label for organizing pages within the knowledge store.
Thread — a conversation originating from GitHub issues, Slack messages, or the Dosu chat. Has messages, a status (pending/resolved/archived), and may trigger document reviews.

Core workflows

1. Finding information

Start with the most direct approach, then broaden:

# Direct question — AI generates an answer from the knowledge base
dosu ask "How does our authentication flow work?" --json

# Semantic search — find relevant documents by similarity
dosu knowledge search "authentication" --json

# Browse by topic — find pages tagged with a specific topic
dosu tags pages <tag-id> --json

Use dosu ask when the user wants an answer. Use dosu knowledge search when they want to find source documents.

2. Creating and managing documentation

# Create from markdown (agents: write to a file first, then pass it)
dosu docs create --title "API Guide" --body-file ./draft.md --json

# AI-generated documentation (async — starts generation in background)
dosu docs generate --title "Onboarding Guide" --instructions "Focus on new developer setup" --json

# AI-suggested documentation topics
dosu suggest generate --json      # Generate suggestions from connected sources
dosu suggest list --json          # List pending suggestions
dosu suggest accept <id> --json   # Accept and create a document from a suggestion

3. Document review and publishing

Documents go through a lifecycle: draft → review → published → synced.

# Check review context for a thread
dosu review context <thread-id> --json

# Approve, reject, or revert a document version
dosu review approve <page-version-id> --json
dosu review reject <page-version-id> --json

# Publish to external platform
dosu docs publish <page-id> --to confluence --parent-page-id <id> --data-source-id <id> --json

# Sync changes back to source (Notion/Confluence bidirectional sync)
dosu docs sync-back <page-id> --json

4. Importing external documentation

Import follows a 3-step pattern: identify files → start import → check status.

# Start import (pass comma-separated IDs)
dosu docs import github --files "file-id-1,file-id-2" --json

# Check progress
dosu docs import-status <task-id> --json

Supported platforms: github, gitlab, confluence, notion, coda. Note: The platform integration must already be connected via the web dashboard before importing.

5. Managing conversations

dosu threads list --status pending --json    # Unresolved threads
dosu threads get <id> --json                 # Thread with messages
dosu threads archive <id> --json             # Archive resolved thread

6. Team and access management

dosu members list --json                          # Current members and invitations
dosu members invite user@example.com --role admin  # Invite (role: admin or member)
dosu members requests --json                       # Pending access requests
dosu members approve user@example.com              # Approve request

7. Checking health and analytics

dosu analytics --days 7 --json    # Usage stats: response count, answer rate, confidence distribution
dosu integrations list --json     # Connection status for all platforms
dosu sources list --json          # Connected data sources

Agent guidelines

Always use `--json`

When acting as an agent, always pass --json to get structured output. Parse the JSON to extract the data you need. Without --json, output is human-formatted with ANSI colors and table formatting that's harder to parse.

Choosing the right command

User intent	Command	Why
"What does X do?" / "How does Y work?"	`dosu ask "<question>"`	AI-generated answer with sources
"Find docs about X" / "Search for X"	`dosu knowledge search "<query>"`	Semantic similarity search
"Show me the document about X"	`dosu docs get <id>`	Direct document retrieval
"Write documentation for X"	`dosu docs generate --title "X"`	AI generates a full document
"What's going on?" / "Any open issues?"	`dosu threads list --status pending`	Pending conversation threads
"How are we doing?" / "Usage stats"	`dosu analytics --days 30`	Usage metrics

Error handling

command not found: dosu → CLI is not installed. Go back to Prerequisites § Step 0 and ask the user to pick an install method. Do not retry dosu until install is verified with dosu --version.
"Not logged in" → Run dosu login (needed for all tRPC commands and hybrid JWT+API-key commands)
"API key not configured" → Run dosu setup (needed for ask, docs generate, docs auto-tag, docs publish)
"Missing space/org config" → Run dosu setup to select a deployment
"No knowledge store found" → The current deployment has no knowledge store configured
"session expired" → The CLI auto-refreshes tokens, but if refresh fails, run dosu login again
tRPC errors → Check the error message; usually a server-side issue or missing data

Authentication notes

Most commands use the user's Supabase access token (from dosu login) to authenticate with the tRPC API. Backend/Python calls still use an API key from dosu setup. A few document commands are hybrid and require both:

Auth method	Commands
Access token (JWT)	All tRPC-backed commands: `threads`, `tags`, `knowledge`, `sources`, `deployments`, `org`, `members`, `integrations`, `review`, `suggest`, `analytics`, and most `docs` commands (`list`, `get`, `create`, `update`, `archive`, `unarchive`, `delete`, `versions`, `restore`, `import`, `import-status`, `sync-back`)
API key only	`ask`
JWT + API key	`docs generate`, `docs auto-tag`, `docs publish`

If the user has run dosu login but not dosu setup, most tRPC commands will work, but ask and the backend-backed doc generation/publishing commands will fail. If the user has run dosu setup but not dosu login, ask may still work, but most of the CLI will not.

Limitations

Connecting new integrations requires the web dashboard (OAuth browser flow). The CLI can view and manage existing integrations, but cannot initiate new OAuth connections.
Billing and subscription management is not available through the CLI.
Document editing accepts markdown strings only — no rich text or WYSIWYG editor.

Reference files

Command reference — Complete command tree with all subcommands
Workflow examples — End-to-end scenarios for common tasks

dosu