@docyrus/docyrus

Docyrus API CLI.

CLI state files are stored under the active .docyrus/ scope.

• Local default: ./.docyrus/
• Global override: ~/.docyrus/ via -g / --global

Tenant OpenAPI files are stored under <settings-root>/tenans/<tenantId>/openapi.json. Pi agent state for docyrus opsy and docyrus cody is stored under <settings-root>/pi/. Knowledge-graph caches and vector indexes are stored under <settings-root>/knowledge/<workspace-hash>/. Tracked repo knowledge lives in docyrus/knowledge/. docyrus tui requires Bun installed locally.

Installation

npm install -g @docyrus/docyrus

or

pnpm add -g @docyrus/docyrus

Authentication

Login with explicit client ID:

docyrus auth login --clientId "<your-client-id>"

After a successful login, the client ID is saved in ~/.docyrus/config.json and reused by default.

Logout active account:

docyrus auth logout

Work with accounts and tenants:

docyrus auth accounts list --json
docyrus auth accounts use --userId "<user-id>" --json
docyrus auth tenants list --userId "<user-id>" --json
docyrus auth tenants use "<tenant-id-uuid-or-tenant-no>" --userId "<user-id>" --json

Environments

The CLI ships with four built-in environments — live, beta, alpha, and dev (aliases: prod → live, local-development → dev). Switch between them with docyrus env use <id|name>.

You can also register your own environments to target self-hosted / on-premise Docyrus deployments:

docyrus env list                                              # built-ins + custom (builtIn flag)
docyrus env add acme --url https://docyrus.acme.internal --name "Acme"
docyrus env use acme
docyrus env update acme --url https://new.acme.internal        # change url and/or --name
docyrus env remove acme                                        # if active, falls back to live

Notes:

• The four built-ins are read-only — you can't add over, update, or remove them.

• Custom environments are saved in the active settings scope. For a machine-wide environment, add it globally so every project sees it:

  docyrus -g env add acme --url https://docyrus.acme.internal

• If your on-premise server uses a self-signed or internal-CA certificate, trust the CA the standard Node way — no insecure flag is needed:

  NODE_EXTRA_CA_CERTS=/path/to/internal-ca.pem docyrus env use acme

Help

docyrus                      # active environment + command overview
docyrus --help

# Environment, auth, and account
docyrus env --help
docyrus auth --help
docyrus account --help

# AI agents
docyrus docy --help          # chat with the main Docyrus AI agent
docyrus opsy --help          # Cowork Agent (interactive pi assistant)
docyrus cody --help          # Coding Agent (alias: docyrus coder)

# Data, schema, and query
docyrus ds --help
docyrus dsql --help
docyrus studio --help
docyrus discover --help

# Apps, automations, and custom agents
docyrus apps --help
docyrus automation --help
docyrus agent --help         # custom-agent CRUD for an app
docyrus acl --help
docyrus messaging --help

# Integrations, knowledge, and releases
docyrus connect --help
docyrus knowledge --help
docyrus project-plan --help
docyrus release --help

# Tools and runtime
docyrus browser --help
docyrus server --help
docyrus tui --help
docyrus curl --help

AI Chat

Chat with the main Docyrus AI agent by sending a single prompt. In an interactive terminal the reply is rendered as markdown; pass --json, --verbose, or --format for machine-readable output.

docyrus docy "How many open tasks are assigned to me?"
docyrus docy "Summarize this week's new leads" --json
docyrus docy "Draft a reply to the latest support ticket" --agentId "<agent-id>"

Browser Automation

Browser automation via a persistent daemon that holds a raw CDP (Chrome DevTools Protocol) WebSocket connection. Works in both local mode (Chrome on :9222) and remote sandbox mode (Cloudflare Browser Rendering).

The daemon starts automatically on the first command and stays alive for 5 minutes of idle time. All commands share the same browser connection.

# Session
docyrus browser start                     # Start Chrome + daemon
docyrus browser start --profile           # Start with user's Chrome profile
docyrus browser close                     # Stop daemon

# Navigation
docyrus browser nav <url>                 # Navigate active tab
docyrus browser nav <url> --new           # Open in new tab

# Waiting
docyrus browser wait --idle               # Wait for network idle
docyrus browser wait --selector "h1"      # Wait for element to appear
docyrus browser wait --url "**/dashboard" # Wait for URL pattern
docyrus browser wait 2000                 # Fixed delay

# Page snapshot and interaction
docyrus browser snapshot                  # Interactive elements with refs (@e1, @e2, ...)
docyrus browser snapshot --all            # Include non-interactive elements
docyrus browser click @e3                 # Click by ref
docyrus browser click 350 200             # Coordinate click (compositor-level)
docyrus browser fill @e1 "value"          # Clear + type into input
docyrus browser select @e4 "Option"       # Select dropdown option

# Inspection
docyrus browser eval 'document.title'     # Evaluate JavaScript
docyrus browser screenshot                # Viewport screenshot
docyrus browser screenshot --full --base64 # Full page as base64
docyrus browser info                      # URL, title, viewport, scroll
docyrus browser console --level error     # Console messages
docyrus browser network --method POST     # Network requests
docyrus browser cookies --name "session"  # Cookies
docyrus browser content <url>             # Extract readable markdown
docyrus browser tabs                      # List/switch tabs

# CDP scripts
docyrus browser run-script script.js      # Run custom CDP script

Knowledge Graph

Initialize and use the repo knowledge graph:

docyrus knowledge init
docyrus knowledge generate-initial
docyrus knowledge refresh
docyrus knowledge locate "Working Agreement" --json
docyrus knowledge section "knowledge#Working Agreement" --json
docyrus knowledge refs "knowledge#Working Agreement" --json
docyrus knowledge search "how should agents use this repo?" --json
docyrus knowledge expand "Read [[Working Agreement]] before editing" --json
docyrus knowledge check --json
docyrus knowledge config --json

Project Plan

The project plan is a repo-tracked work graph stored at docyrus/project-plan/project-plan.json. It organizes work into phases, features, and tasks. A derived PROJECT_PLAN.md is always kept in sync. Features are also synced into the knowledge base features document when it exists.

Manage phases, features, and tasks:

docyrus project-plan show --json
docyrus project-plan check --json
docyrus project-plan ensure --json
docyrus project-plan summary --json
docyrus project-plan config --json

# Token-efficient slices (prefer over `show` for large plans)
docyrus project-plan list-phases --json
docyrus project-plan list-features --json
docyrus project-plan list-tasks --status planned --limit 5 --json
docyrus project-plan list-tasks --status in_progress --json
docyrus project-plan list-tasks --phaseId "<phase-id>" --featureId "<feature-id>" --includeSummary true --json

# Phases
docyrus project-plan upsert-phase --title "Core Features" --json
docyrus project-plan upsert-phase --title "Testing" --slug "testing" --summary "Test coverage" --json

# Features
docyrus project-plan upsert-feature --phaseId "<phase-id>" --title "Auth Flow" --json
docyrus project-plan upsert-feature --phaseId "<phase-id>" --title "Data Export" --slug "data-export" --summary "CSV and JSON export" --json

# Tasks
docyrus project-plan upsert-task --featureId "<feature-id>" --title "Implement OAuth2" --type new-implementation --assignee agent --json
docyrus project-plan upsert-task --featureId "<feature-id>" --title "Fix token refresh" --type bug-fix --assignee agent --status in_progress --json
docyrus project-plan get-task --taskId "<task-id>" --json
docyrus project-plan set-task-status --taskId "<task-id>" --status done --json
docyrus project-plan set-order --phaseId "<phase-id>" --order 1 --json

# Linked local subtasks
docyrus project-plan create-linked-todo --taskId "<task-id>" --json
docyrus project-plan create-linked-todo --taskId "<task-id>" --title "Step 1" --body "Details" --json

Task types: new-implementation, bug-fix, api-test, browser-automation-test, work Assignees: agent, user Statuses: planned, in_progress, blocked, done

Release

Create versioned releases with changelog generation:

docyrus release status --json
docyrus release new-version --json
docyrus release new-version --bump major --json
docyrus release new-version --version 2.0.0 --json
docyrus release new-version --dryRun --json
docyrus release new-version --skipChangelog --skipTag --json
docyrus release new-version --skipGithubRelease --json

The new-version command bumps the version in package.json, generates a categorized changelog from commit history, creates a git tag, and optionally publishes a GitHub release via gh.

Data Sources

Query data source items:

docyrus ds list base task --columns "id,name,status" --limit 10 --orderBy "created_on desc" --json

Create, update, delete data source items:

docyrus ds create base task --data '{"name":"My Task","status":"open"}' --json
docyrus ds update base task "<record-id>" --data '{"status":"done"}' --json
docyrus ds delete base task "<record-id>" --json

Add comments and file attachments to a record:

docyrus ds comments create base task "<record-id>" --message "Looks good" --json
docyrus ds files upload base task "<record-id>" --file ./contract.pdf --json

Batch create/update (max 50 items) and file input (--from-file supports .json and .csv):

docyrus ds create base task --data '[{"name":"Task 1"},{"name":"Task 2"}]' --json
docyrus ds update base task --data '[{"id":"1","status":"done"},{"id":"2","status":"open"}]' --json
docyrus ds create base task --from-file ./tasks.csv --json
docyrus ds update base task --from-file ./tasks-update.json --json

DSQL (Logical SQL)

Run read-only logical SQL against your data sources, generate queries from natural language, inspect schemas, and manage saved custom queries.

docyrus dsql query "<sql>" --json
docyrus dsql generate "open tasks assigned to me" --json
docyrus dsql ask "how many tasks are open?" --json
docyrus dsql schema app base --json
docyrus dsql schema data-source base task --json
docyrus dsql list-custom-query --appSlug base --json
docyrus dsql create-custom-query --appSlug base --name "Open Tasks" --dsqlQuery "<sql>" --fields '<json>' --json
docyrus dsql run-custom-query --queryId "<id>" --json

OpenAPI Discovery

Download current tenant OpenAPI spec:

docyrus discover api --json

Discover from downloaded tenant OpenAPI spec:

docyrus discover namespaces --json
docyrus discover path /v1/users --json
docyrus discover endpoint /v1/users/me --json
docyrus discover endpoint [PUT]/v1/users/me/photo --json
docyrus discover entity UserEntity --json
docyrus discover search users,UserEntity --json

Connectors

docyrus connect list-connectors --json
docyrus connect get-connector <slug> --json
docyrus connect get-action <slug> <actionKey> --json
docyrus connect list-connections <slug> --json
docyrus connect curl <slug> <endpoint> --json
docyrus connect run-action <appSlug> <actionKey> --json

Apps and Studio

List and manage apps:

docyrus apps list --json
docyrus apps delete --appId "<app-id>" --json
docyrus apps restore --appId "<app-id>" --json

Manage dev studio data sources, fields, and enums:

docyrus studio list-data-sources --appSlug base --expand fields --json
docyrus studio get-data-source --appSlug base --dataSourceSlug task --json
docyrus studio create-data-source --appSlug base --title "Tasks" --name "task" --slug "task" --json
docyrus studio update-data-source --appId "<app-id>" --dataSourceId "<data-source-id>" --data '{"title":"Tasks v2"}' --json
docyrus studio delete-data-source --appId "<app-id>" --dataSourceSlug "task" --json
docyrus studio bulk-create-data-sources --appId "<app-id>" --from-file ./data-sources.json --json
docyrus studio list-fields --appSlug base --dataSourceSlug task --json
docyrus studio get-field --appSlug base --dataSourceSlug task --fieldSlug status --json
docyrus studio create-field --appId "<app-id>" --dataSourceId "<data-source-id>" --name "Status" --slug "status" --type "text" --json
docyrus studio update-field --appId "<app-id>" --dataSourceId "<data-source-id>" --fieldId "<field-id>" --data '{"name":"Stage"}' --json
docyrus studio delete-field --appId "<app-id>" --dataSourceId "<data-source-id>" --fieldSlug "status" --json
docyrus studio create-fields-batch --appId "<app-id>" --dataSourceId "<data-source-id>" --data '[{"name":"Priority","slug":"priority","type":"text"}]' --json
docyrus studio update-fields-batch --appId "<app-id>" --dataSourceId "<data-source-id>" --from-file ./fields-update.json --json
docyrus studio delete-fields-batch --appId "<app-id>" --dataSourceId "<data-source-id>" --data '["field-1","field-2"]' --json
docyrus studio list-enums --appId "<app-id>" --dataSourceId "<data-source-id>" --fieldId "<field-id>" --json
docyrus studio create-enums --appId "<app-id>" --dataSourceId "<data-source-id>" --fieldId "<field-id>" --data '[{"name":"Open","sortOrder":1}]' --json
docyrus studio update-enums --appId "<app-id>" --dataSourceId "<data-source-id>" --fieldId "<field-id>" --from-file ./enums-update.json --json
docyrus studio delete-enums --appId "<app-id>" --dataSourceId "<data-source-id>" --fieldId "<field-id>" --data '["enum-1","enum-2"]' --json

Tenant-wide search across data sources (returns { data, meta: { total, limit, offset } }):

# Fields, with multi-value filters and keyword
docyrus studio search-fields --keyword email --json
docyrus studio search-fields --dataSourceId "<id1>,<id2>" --type field-text,field-textarea --limit 50 --json
docyrus studio search-fields --keyword status --offset 100 --limit 50 --json

# Enums, joined with data source / field / enum set
docyrus studio search-enums --dataSourceId "<data-source-id>" --json
docyrus studio search-enums --enumSetId "<enum-set-id>" --json
docyrus studio search-enums --fieldId "<field-id>" --limit 200 --json

# Enum sets
docyrus studio search-enum-sets --limit 50 --offset 0 --json

Automations

Manage an app's automations and their triggers (trigger --type values are kebab-case, e.g. record-created, recurrence, webhook).

docyrus automation list --appSlug base --json
docyrus automation get --appId "<app-id>" --automationId "<id>" --json
docyrus automation create --appSlug base --from-file ./automation.json --json
docyrus automation create-trigger --appSlug base --automationId "<id>" --type record-created --json
docyrus automation delete-trigger --appSlug base --automationId "<id>" --triggerId "<id>" --json

Custom Agents

CRUD for an app's custom agents and their sub-resources (models, tools, data sources, deployments, and more). Run docyrus agent --help for the full resource list.

docyrus agent list --appSlug base --json
docyrus agent create --appSlug base --name "Support Bot" --skillName "support" --json
docyrus agent tools create --appSlug base --agentId "<id>" --toolType "<type>" --json
docyrus agent deployments list --appSlug base --agentId "<id>" --json

Access Control

Manage tenant roles, role queries, and user hierarchy units.

docyrus acl roles list --json
docyrus acl roles create --slug "<slug>" --name "<name>" --json
docyrus acl role-queries list --json
docyrus acl hierarchy-units list --json
docyrus acl hierarchy-units create --name "<name>" --json

Messaging

Inspect tenant email accounts (non-credential info) and send email through them.

docyrus messaging accounts --json
docyrus messaging email send --accountId "<id>" --json

Account

Manage tenant brands, your own user profile, and tenant regional preferences.

docyrus account brands list --json
docyrus account brands create --name "<name>" --json
docyrus account user-profile get --json
docyrus account user-profile update --firstname "<name>" --json
docyrus account tenant-preferences get --json
docyrus account tenant-preferences update --timeZone "<id>" --json

Raw API Access

docyrus curl /users/me -i --json
docyrus curl /dev/apps --json

TUI

Launch the OpenTUI terminal UI (requires Bun):

docyrus tui

Agent Server

Start the agent HTTP server:

docyrus server
docyrus server --port 4000
docyrus server --profile agent
docyrus server --model anthropic/claude-sonnet-4-20250514 --thinking high
docyrus server --auth "<bearer-token>"
docyrus server --apiKey "<key>" --provider azure-openai-responses

The server exposes REST endpoints for chat, models, knowledge, project-plan, release, files, and dev environment management. It also attaches a WebSocket PTY terminal at WS /api/terminal for interactive shell access.

For full endpoint documentation see docs/API.md.

Pi Agent and Coding Agent

Launch the scoped pi assistant and coding agent:

# Interactive TUI
# First interactive launch opens the DOCYRUS onboarding wizard if no provider is configured yet.
docyrus opsy
docyrus cody

# Interactive TUI with an initial prompt
docyrus opsy "Inspect the active tenant and list apps"
docyrus cody "Add a command to list my team dashboards"

# One-shot mode
docyrus opsy --print "Which tenant am I using?"
docyrus cody --print --mode json "Summarize the CLI command surface in this repo"

docyrus coder remains as an alias of docyrus cody.

Built-in Agent Tools

When docyrus/knowledge/ exists, docyrus opsy, docyrus cody, and docyrus server load built-in knowledge tools:

• docyrus_knowledge_search
• docyrus_knowledge_section
• docyrus_knowledge_locate
• docyrus_knowledge_refs
• docyrus_knowledge_expand
• docyrus_knowledge_check

When docyrus/project-plan/project-plan.json exists, the agents use project-plan CLI commands (docyrus project-plan show, set-task-status, create-linked-todo, etc.) to read and update the canonical work graph.

The todo tool is always available with actions: list, list-all, get, create, update, append, delete, claim, release.

Slash Commands

Inside the interactive agent TUI:

/login            # browser or API-key provider chooser
/logout           # remove saved provider configuration
/plan [task]      # start a planning-only branch and keep the current plan in .docyrus/plans/
/end-plan         # leave the planning branch, summarize it, and return to the original branch
/plan-policy      # show the effective planning-model policy and the resolved planning model
/read-only        # enter read-only mode — write and edit tools are disabled
/end-read-only    # exit read-only mode and resume normal operation
/tasks            # browse the canonical project-plan phases, features, and tasks
/todos            # interactive todo manager
/souls            # list available agent "souls" (communication styles)
/soul <id>        # switch the agent's soul (e.g. caveman, master-yoda, pirate) — takes effect next session

Souls

A "soul" is a style-only prompt overlay that changes how the agent talks without changing what it does. Tool usage, Docyrus CLI rules, and structured (--json) output are always preserved; souls only affect narrative prose.

Select a soul inside the pi agent (docyrus opsy / docyrus cody) with /soul <id> and list available souls with /souls. The selection is persisted in <settings-root>/config.json (same scope as environment/auth) and takes effect on the next agent session.

Over HTTP (docyrus server):

curl http://localhost:3111/api/souls
curl -X POST http://localhost:3111/api/souls/select \
  -H 'content-type: application/json' \
  -d '{"soulId":"pirate"}'

Full server API reference for Soul, MCP, and Skill endpoints: docs/server-api.md.

Full REST API reference for the Project Plan and Goal endpoints: docs/project-plan-goal-api.md (machine-readable OpenAPI 3.1 spec: docs/project-plan-goal-openapi.yaml).

When running through docyrus server, /plan can be sent through /api/chat as normal chat input. If clarification is needed, the server emits a synthetic ask_user client tool. Frontends using AI SDK useChat should render that tool and submit structured answers back with addToolOutput.

Planning-Model Policy

Optional planning-model policy for controlling which model is used during /plan sessions:

• Project config: <project>/.pi/plan-policy.json
• Global config: ~/.pi/agent/plan-policy.json
• Project config takes precedence over global config

Example:

{
  "models": [
    { "model": "anthropic/claude-sonnet-4", "thinkingLevel": "high" },
    "openai-codex/gpt-5.3-codex"
  ],
  "profiles": {
    "codex-implementation": {
      "match": "openai-codex/gpt-5.3-codex",
      "models": [
        { "model": "anthropic/claude-sonnet-4", "thinkingLevel": "medium" }
      ]
    }
  }
}

match is the exact implementation-time provider/modelId active when /plan starts. The models array is an ordered fallback chain. If no configured planning model resolves, /plan stays on the current session model.