Dosu

Use the Dosu CLI

Operate Dosu through dosu. Prefer structured output and let the CLI and App validate product rules.

Start correctly

1. Run dosu --version. Do not probe installation with unrelated package-manager commands.
2. If it is unavailable and Node is present, try npx -y @dosu/cli --version and use npx -y @dosu/cli as the command prefix for this session. Otherwise ask before installing anything.
3. Run dosu --help or the relevant nested --help before using a command not covered by the command reference.
4. Pass --json whenever that leaf command exposes it. Parse the result; do not scrape the human table.

Satisfy the right prerequisite

• dosu login supplies the JWT used by tRPC-backed commands.
• dosu setup selects an organization, Library context, and MCP deployment, creates an API key, and can configure an agent tool.
• dosu ask needs an API key. docs generate, docs auto-tag, and docs publish need both JWT login and the API key. Other platform commands generally need JWT login; commands scoped to an organization or current Library also need the corresponding setup selection.
• For coding-agent setup, follow the nonblocking dosu setup --agent --tool <id> workflow in workflows.md. Relay its URL and execute its returned resume_command; never invent ticket commands.

Use current product terms

• Organization is the account and permission boundary.
• Library is the knowledge container shown in the App. Older APIs may call it a space; do not present that internal name to users.
• Data source is an organization-level connection such as a repository, Slack channel, or Notion workspace. A Library can use already-connected sources.
• Agent is a configurable GitHub, GitLab, Slack, or Teams deployment serving exactly one Library.
• Monitor is per Library and source. It supports GitHub, GitLab, and Azure DevOps sources.
• dosu deployments manages selectable MCP deployments. Do not use it as an Agent CRUD command.

Route by intent

Use commands.md as the sole detailed command and flag reference. Use workflows.md only for multi-command composition.

Apply Library and Agent semantics

• To assemble a Library, list organization sources, create the Library, attach the chosen source IDs, then verify with libraries info and libraries sources list. The CLI cannot establish a brand-new OAuth connection.
• libraries sources config resolves the provider on the App side. Read the command reference before choosing provider-specific options.
• When creating a Library with a GitHub repository, or newly attaching one to an existing Library, treat Monitor as part of that setup unless the user opts out. Enable it with the whole-repository and emoji defaults, verify it, and explain that Monitor reviews pull requests to keep the Library's knowledge up to date. Follow the Library workflow; do not ask the user to choose defaults.
• Create an Agent from an existing source ID and let the App choose its defaults; do not synthesize config in shell commands.
• Read Agent config before changing one existing leaf. Values are JSON. If a concurrent write returns CONFLICT, read again, re-evaluate the requested change, and retry only if it is still correct.
• Moving an Agent replaces its Library. Verify the returned space_id; do not infer migration behavior for historical data from the move receipt.

Respect write boundaries

• Treat an explicit, unambiguous user request for the exact mutation as authorization. Otherwise show the intended change and wait for confirmation.
• For commands exposing --confirm, omit it first when a preview is useful; { "confirmRequired": true, "applied": false } means nothing changed. Pass --confirm only after authorization.
• Never batch-approve or batch-reject review items. Diff one item, explain it, and decide only the ID the user authorized.
• Before deleting a Library, Agent, source, or document, state the exact target and impact. Before detaching a source, read and state the impact documented in the command reference. Some older delete commands do not enforce --confirm; the absence of a CLI prompt is not user approval.
• Before attaching a source to a public Library, warn that its content becomes available to everyone who can access that Library.
• OAuth connection and billing remain web-only. Report the boundary instead of claiming success.

Handle failures literally

• Not logged in or an unrecoverable expired session: run dosu login (agent setup may instead return a ticket flow).
• Missing organization, Library, deployment, or API-key context: run the appropriate dosu setup flow.
• confirmRequired: no write occurred.
• CONFLICT on config: reread before retrying.
• A tRPC or backend error is a failed operation. Surface the code/path/status and do not imply the requested state exists.

References

• commands.md: authoritative CLI syntax, choices, defaults, conflicts, and prerequisites
• workflows.md: reusable multi-command flows
• review-workflow.md: review safety and context
• audit.md: repository audit procedure
• audit-findings-schema.md: .dosu/audit.json contract