Docyrus CLI

Guide for using the docyrus CLI (@docyrus/docyrus) to interact with the Docyrus platform from the terminal.

Command Overview

See references/cli-manifest.md for the complete command reference with flags and arguments.

Flag forms: --help prints flags in kebab-case (--app-slug, --from-file), but the parser also accepts the camelCase schema keys (--appSlug, --fromFile). This guide uses the camelCase form; both work.

Common Workflows

Settings Scope

By default, docyrus stores settings in a project-local .docyrus/ folder in the current working directory.

• Local default: ./.docyrus/
• Global override: ~/.docyrus/ via -g or --global
• Tenant OpenAPI cache: <settings-root>/tenans/<tenantId>/openapi.json

# Local project settings (default)
docyrus auth login --clientId "83a8df32-3738-4b5a-a0c7-87976adb1631"

# Force global settings for this run
docyrus -g auth login --clientId "83a8df32-3738-4b5a-a0c7-87976adb1631"

# Inspect which scope/environment is active for this folder
docyrus env which --json

env which reports local/global scope, the resolved settingsRoot, configFilePath, authFilePath, cwd, and whether a local .docyrus/ directory exists.

Environments

The CLI does not use API_BASE_URL. It uses saved named environments:

• live (prod alias) -> https://api.docyrus.com
• beta -> https://beta-api.docyrus.com
• alpha -> https://alpha-api.docyrus.com
• dev (local-development alias) -> https://localhost:3366

docyrus
docyrus env list --json
docyrus env use beta --json

Running docyrus without a subcommand returns the active environment, help summary, and current auth context.

Authentication

Device flow login:

docyrus auth login --clientId "83a8df32-3738-4b5a-a0c7-87976adb1631" --json

Manual token login (auth login or auth set-tokens):

docyrus auth login \
  --accessToken "<access-token>" \
  --refreshToken "<optional-refresh-token>" \
  --clientId "<optional-client-id>" \
  --json

docyrus auth set-tokens --accessToken "<access-token>" --refreshToken "<refresh-token>" --json

Rules:

• --refreshToken requires --accessToken
• if local login omits --clientId, the CLI falls back to the saved global client ID when available
• client ID resolution order: --clientId -> DOCYRUS_API_CLIENT_ID -> saved local config -> saved global config -> manual-token (manual auth only)
• default scopes are hardcoded: openid email profile offline_access ReadWrite.All Architect.ReadWrite.All Automations.Run Reports.Run.CustomQuery Messaging.Email.Send Messaging.Sms.Send Messaging.Whatsapp.Send MCP.Connect

Multi-account and multi-tenant workflows:

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 1002 --json
docyrus auth tenants use "8d130f7a-4bc4-4be6-a05b-0f8f1b2d93e9" --userId "<user-id>" --json
docyrus auth who --json
docyrus auth tenant --json

auth tenants use takes a positional tenant selector. Numeric -> tenantNo; otherwise it must be a UUID tenant ID.

auth tenant (singular) returns the active tenant record from GET /v1/tenant/current (id, no, name, account status, product/subscription refs, seats, billing, trial/subscription dates, onboarding status). It is a read-only passthrough like auth who; don't confuse it with the auth tenants (plural) account-management group.

Sandbox / CI token helpers (auth sandbox, auth github, auth sso-session, auth git-credential) inject fresh tokens into a running sandbox app, mint repo-scoped GitHub tokens, or create short-lived SSO sessions for headless browsers. They default --appId to DOCYRUS_SANDBOX_APP_ID and are mostly used by the sandbox runtime rather than by hand.

Successful Result Shape

Every successful command injects a top-level context field:

{
  "data": {},
  "context": {
    "email": "user@example.com",
    "tenantName": "Acme",
    "tenantNo": 1002,
    "tenantDisplay": "Acme (1002)"
  }
}

If there is no active session, context is null.

Discover API and Entities

Discover commands require an active session. Commands other than discover api auto-download the OpenAPI spec if it is missing locally.

docyrus discover api --json
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

Discover Data Sources

docyrus apps list --json
docyrus ds get crm contacts --json

Query Records (ds list)

Basic listing:

docyrus ds list crm contacts --columns "name, email, phone" --limit 20

With filters:

docyrus ds list crm contacts \
  --columns "name, email" \
  --filters '{"rules":[{"field":"status","operator":"=","value":"active"}]}'

With relation expansion:

docyrus ds list crm contacts \
  --columns "name, ...related_account(account_name, account_phone)"

Keyword filter and date shortcut:

docyrus ds list crm tasks --filterKeyword "renewal"
docyrus ds list crm tasks --filters '{"rules":[{"field":"created_on","operator":"this_month"}]}'

ds list also supports the full query engine: --formulas, --calculations, --groupSummaries, --pivot, --childQueries, --expand, --distinctColumns, and --collapseRows.

See references/list-query-examples.md for columns, filters, sorting, pagination, and advanced (formulas/calculations/pivot/child-query) examples.

Record Mutations

Create / update / delete:

docyrus ds create crm contacts --data '{"name":"Jane Doe","email":"jane@example.com"}'
docyrus ds update crm contacts <recordId> --data '{"phone":"+1234567890"}'
docyrus ds delete crm contacts <recordId>

Batch and file input:

docyrus ds create crm contacts --data '[{"name":"A"},{"name":"B"}]' --json
docyrus ds update crm contacts --data '[{"id":"1","phone":"+111"},{"id":"2","phone":"+222"}]' --json
docyrus ds create crm contacts --from-file ./contacts-create.csv --json
docyrus ds update crm contacts <recordId> --from-file ./contact-update.json --json

Array payloads route to bulk endpoints and are limited to 50 items per request.

Record Comments and File Attachments

# Add a comment to a record
docyrus ds comments create crm contacts <recordId> --message "Followed up by phone" --json
docyrus ds comments create crm contacts <recordId> --from-file ./comment.json --json

# Upload a file attachment to a record (multipart/form-data)
docyrus ds files upload crm contacts <recordId> --file ./contract.pdf --json
docyrus ds files upload crm contacts <recordId> --file ./logo.png --publicFile --json

Comment accepts either --message or a full DTO via --data/--from-file. Uploads infer content type from the file extension unless --contentType is set; --publicFile stores in the public tenant bucket.

Studio Schema CRUD (studio)

Use studio for developer-facing schema operations: data sources, fields, enums, saved views, forms, webforms, and export templates. Most data-source-scoped commands accept either --appId/--appSlug and either --dataSourceId/--dataSourceSlug, and the CLI resolves whichever side you did not pass.

# Data sources
docyrus studio list-data-sources --appSlug crm --expand fields --json
docyrus studio get-data-source --appSlug crm --dataSourceSlug contacts --json
docyrus studio create-data-source --appSlug crm --title "Contacts" --name "contacts" --slug "contacts" --json
docyrus studio update-data-source --appId <appId> --dataSourceId <dataSourceId> --data '{"title":"Contacts v2"}' --json
docyrus studio delete-data-source --appId <appId> --dataSourceSlug contacts --json
docyrus studio restore-data-source --appId <appId> --dataSourceId <dataSourceId> --json
docyrus studio permanent-delete-data-source --appId <appId> --dataSourceId <dataSourceId> --json
docyrus studio bulk-create-data-sources --appId <appId> --from-file ./data-sources.json --json

# Fields
docyrus studio list-fields --appSlug crm --dataSourceSlug contacts --json
docyrus studio get-field --appSlug crm --dataSourceSlug contacts --fieldSlug email --json
docyrus studio create-field --appId <appId> --dataSourceId <dataSourceId> --name "Email" --slug "email" --type "text" --json
docyrus studio update-field --appId <appId> --dataSourceId <dataSourceId> --fieldId <fieldId> --data '{"name":"Primary Email"}' --json
docyrus studio delete-field --appId <appId> --dataSourceId <dataSourceId> --fieldSlug email --json
docyrus studio create-fields-batch --appId <appId> --dataSourceId <dataSourceId> --data '[{"name":"Status","slug":"status","type":"text"}]' --json
docyrus studio update-fields-batch --appId <appId> --dataSourceId <dataSourceId> --from-file ./fields-update.json --json
docyrus studio delete-fields-batch --appId <appId> --dataSourceId <dataSourceId> --data '["field-1","field-2"]' --json

# Enums
docyrus studio list-enums --appId <appId> --dataSourceId <dataSourceId> --fieldId <fieldId> --json
docyrus studio create-enums --appId <appId> --dataSourceId <dataSourceId> --fieldId <fieldId> --data '[{"name":"Open","sortOrder":1}]' --json
docyrus studio update-enums --appId <appId> --dataSourceId <dataSourceId> --fieldId <fieldId> --from-file ./enums-update.json --json
docyrus studio delete-enums --appId <appId> --dataSourceId <dataSourceId> --fieldId <fieldId> --data '["enum-1","enum-2"]' --json

# Cross-data-source search (tenant-wide, paged) — useful for discovery/refactors
docyrus studio search-fields --keyword "email" --type "text,email" --json
docyrus studio search-enums --dataSourceId <dataSourceId> --json
docyrus studio search-enum-sets --limit 50 --json

# Data views (/v1/apps/:appSlug/data-sources/:dataSourceSlug/views)
docyrus studio list-data-views --appSlug crm --dataSourceSlug contacts --json
docyrus studio create-data-view --appSlug crm --dataSourceSlug contacts --name "Active customers" \
  --filters '{"rules":[{"field":"status","operator":"=","value":"active"}]}' --isDefault --json
docyrus studio update-data-view --appSlug crm --dataSourceSlug contacts --viewId <viewId> --data '{"name":"Renamed view"}' --json
docyrus studio delete-data-view --appSlug crm --dataSourceSlug contacts --viewId <viewId> --json

# Forms (/v1/apps/:appSlug/data-sources/:dataSourceSlug/forms)
docyrus studio create-form --appSlug crm --dataSourceSlug contacts --name "Lead intake" --title "New lead" --json
docyrus studio update-form --appSlug crm --dataSourceSlug contacts --formId <formId> --data '{"title":"Renamed"}' --json

# Webforms (/v1/dev/webforms)
docyrus studio create-webform --appSlug crm --dataSourceSlug contacts --from-file ./contact-webform.json --json
docyrus studio update-webform --webformId <webformId> --data '{"name":"Renamed"}' --json

# HTML / PDF / DOCX export templates (/v1/dev/html-templates)
docyrus studio create-html-template --appSlug crm --dataSourceSlug contacts \
  --name "Invoice" --sourceType pdf --pageFormat A4 --pageOrientation portrait \
  --body "<h1>{{ company.name }}</h1>" --isDefault --json

# Email templates (/v1/dev/email-templates)
docyrus studio create-email-template --name "Welcome" --subject "Hello {{ user.name }}" --body "<p>Hi</p>" --json

App Management (apps)

apps list uses /v1/apps; mutations route through /v1/dev/apps/:appId.

docyrus apps list --json
docyrus apps update --appSlug crm --description "Customer CRM" --color "#2563eb" --json
docyrus apps delete --appId <appId> --json
docyrus apps restore --appId <appId> --json
docyrus apps permanent-delete --appId <appId> --json

apps update accepts camelCase convenience flags (--name, --slug, --description, --icon, --color, --status, --betaUrl, --chromeExtensionPath, --mobileVersionPath, --agentContext, --routePath) merged over --data/--from-file. Store fields and array/object values must go through --data/--from-file. --status is one of active, design, development, draft, inactive.

App AI Agent Context

Set the freeform AI agent context an app injects into its agents (PATCH /v1/dev/apps/:appId agent_context):

docyrus apps set-agent-context --appSlug crm --value "This app manages B2B sales pipelines." --json
docyrus apps set-agent-context --appSlug crm --from-file ./agent-context.md --json
docyrus apps set-agent-context --appSlug crm --clear --json

Provide exactly one of --value (inline), --from-file (raw text/markdown), or --clear.

App-Scoped Actions (apps actions)

CRUD over standalone tenant_action rows scoped to an app (/v1/dev/apps/:appId/actions), plus the action-type picker and run:

docyrus apps actions list --appSlug crm --json
docyrus apps actions types --appSlug crm --json            # selectable action types (excludes create/update-record + wait-for; color = Tailwind name)
docyrus apps actions get --appSlug crm --actionId <id> --json
docyrus apps actions create --appSlug crm --name "Request barcode" --coreActionId <coreActionId> \
  --options '{"shipmentPackageId":987654}' --json
docyrus apps actions update --appSlug crm --actionId <id> --status 2 --json
docyrus apps actions delete --appSlug crm --actionId <id> --json
docyrus apps actions run --appSlug crm --actionId <id> --data '{"foo":"x"}' --json

--name and --coreActionId are required on create; --coreActionId is create-only (immutable, rejected on update). Convenience flags cover the common columns; JSON fields (--options, --conditions, --customHeaders, --inputTransformer, --inputTemplate, --inputJsonSchema, --outputJsonSchema, …) are parsed from JSON, and the long tail can go through --data/--from-file. run posts the body as the action input record to the slug-based public endpoint (/v1/apps/:appSlug/actions/:actionId/run); it accepts --appId too (reverse-resolved to the slug).

App-Scoped AI Tools (apps ai-tools)

Full CRUD over tenant_ai_tool rows scoped to an app (/v1/dev/apps/:appId/ai-tools):

docyrus apps ai-tools list --appSlug crm --json
docyrus apps ai-tools get --appSlug crm --toolId <toolId> --json
docyrus apps ai-tools create --appSlug crm --name "Lookup contact" --key lookup_contact \
  --type data-source-query --dataSourceQueryDataSourceId <dataSourceId> --json
docyrus apps ai-tools update --appSlug crm --toolId <toolId> --description "Updated" --json
docyrus apps ai-tools delete --appSlug crm --toolId <toolId> --json

--name and --key are required on create. Convenience flags cover the common columns; complex/JSON fields (--inputJsonSchema, --outputJsonSchema, --customQueryFilters, --dataSourceQueryColumns, etc.) are parsed from JSON, and the long tail can go through --data/--from-file. Platform-managed fields (group, avatar, restricted, cost, development_status, owner_product_id, core_action_id, core_data_provider_id) are not settable on app-scoped tools.

Automations (automation)

Manage automations, their triggers, and action nodes for an app. All commands route through /v1/dev/apps/:appId/automations. App is resolved with --appId or --appSlug. Automations and nodes have IDs only (no slugs).

# Automation CRUD
docyrus automation list --appSlug crm --json
docyrus automation get --appSlug crm --automationId <automationId> --json
docyrus automation create --appSlug crm \
  --name "Notify on new deal" --triggerType recordCreated \
  --sourceDataSourceId <dataSourceId> --status 1 --json
docyrus automation update --appSlug crm --automationId <automationId> \
  --data '{"name":"Renamed automation","status":1}' --json
docyrus automation delete --appSlug crm --automationId <automationId> --json

# Triggers (typed create/update, type-independent delete)
docyrus automation list-triggers --appSlug crm --automationId <automationId> --json
docyrus automation create-trigger --appSlug crm --automationId <automationId> \
  --type record-modified --sourceDataSourceId <dataSourceId> \
  --modifiedColumns "status,stage" --modifiedColumnsCondition any --json
docyrus automation create-trigger --appSlug crm --automationId <automationId> \
  --type recurrence --recurrenceFrequency day --recurrenceInterval 1 --recurrenceRunAt "09:00" --json
docyrus automation create-trigger --appSlug crm --automationId <automationId> \
  --type app-event --dataProviderId <coreDataProviderId> --dataProviderWebhookId <webhookId> --json
docyrus automation update-trigger --appSlug crm --automationId <automationId> \
  --type webhook --triggerId <triggerId> --data '{"webhook_name":"renamed"}' --json
docyrus automation delete-trigger --appSlug crm --automationId <automationId> --triggerId <triggerId> --json

# Action nodes (typed create/update, type-independent delete)
docyrus automation list-nodes --appSlug crm --automationId <automationId> --json
docyrus automation create-node --appSlug crm --automationId <automationId> \
  --type http-request --requestMethod POST --customEndpoint "https://example.com/webhook" \
  --contentType "application/json" --from-file ./http-node.json --json
docyrus automation create-node --appSlug crm --automationId <automationId> \
  --type external-action --actionTypeId <coreActionId> --from-file ./external-action.json --json
docyrus automation update-node --appSlug crm --automationId <automationId> \
  --type send-email --nodeId <nodeId> --data '{"data":{"to":"user@example.com","subject":"Hi"}}' --json
docyrus automation create-node --appSlug crm --automationId <automationId> \
  --type wait-for --name "Wait 2 hours" --parent <previousNodeId> \
  --data '{"data":{"delayValue":2,"delayUnit":"hours"}}' --json
docyrus automation delete-node --appSlug crm --automationId <automationId> --nodeId <nodeId> --json

Trigger --type values (kebab-case URL form): record-created, record-modified, record-deleted, recurrence, app-event, webhook, emailhook, webform, button-activation, manual-activation.

Node --type values (kebab-case URL form): external-action, send-email, send-notification, create-record, update-records, request-approval, request-input, http-request, data-source-query, custom-query, generate-document, ai-prompt, ai-agent, execute-script, wait-for.

Notes:

• automation create --triggerType uses the camelCase form (recordCreated, recordModified, …) to match CreateAutomationDto.trigger_type; trigger CRUD commands use kebab-case for --type.
• Convenience flags are camelCase on the CLI but converted to snake_case in the request body. Complex nested objects (trigger data, node data, field_mapping, dynamic_field_mapping, condition, input_template, input_transformer, custom_headers, pre_action_request, post_action_request, target_data_source_condition, …) must be supplied via --data/--from-file. --recurrenceWeekDays and --modifiedColumns accept comma-separated values sent as arrays.
• app-event triggers use --dataProviderId and --dataProviderWebhookId (obtain via docyrus connect list-connectors / connect get-connector <slug>); webform triggers use --webformId.
• create-node --type external-action requires --actionTypeId; the backend validates the supplied data against the linked core_action.input_json_schema.
• create-node --type wait-for takes no flat flags beyond the common base. Set the delay inside data: either delaySeconds (integer, capped at 30 days / 2_592_000) or the delayValue + delayUnit (seconds/minutes/hours/days) pair.

Custom AI Agents (agent)

CRUD for dev-app custom agents and their sub-resources, routed through /v1/dev/apps/:appId/agents.... App is resolved with --appId/--appSlug; the parent agent is --agentId; an individual sub-resource row is --id.

# Agent resource
docyrus agent list --appSlug crm --json
docyrus agent get --appSlug crm --agentId <agentId> --json
docyrus agent create --appSlug crm --skillName "sales_copilot" --name "Sales Copilot" \
  --description "Assists with deal updates" --defaultAiModelId <modelId> --supportTools --json
docyrus agent update --appSlug crm --agentId <agentId> --welcomeMessage "Hi!" --json
docyrus agent delete --appSlug crm --agentId <agentId> --json
docyrus agent upload --appSlug crm --agentId <agentId> --column avatar --file ./avatar.png --json

# Sub-resources (each: list / get / create / update / delete, unless noted)
docyrus agent models   create --appSlug crm --agentId <agentId> --from-file ./model.json --json
docyrus agent tools    create --appSlug crm --agentId <agentId> --coreAiToolId <toolId> --json
docyrus agent data-sources create --appSlug crm --agentId <agentId> --tenantDataSourceId <dataSourceId> --json
docyrus agent docs     create --appSlug crm --agentId <agentId> --from-file ./doc.json --json
docyrus agent mcps     create --appSlug crm --agentId <agentId> --from-file ./mcp.json --json
docyrus agent connections create --appSlug crm --agentId <agentId> \
  --connectedAiAgentId <agentId> --connectionType handoff --json
docyrus agent deployments create --appSlug crm --agentId <agentId> --from-file ./deployment.json --json
docyrus agent workflow-jobs list --appSlug crm --agentId <agentId> --json   # read-only (+ get / traces / delete)

Sub-resource groups: models, tools, data-sources, docs, mcps, connections, dynamic-contexts, tasks, recurring-tasks, workflow-steps, deployments, deployment-tools (nested under a deployment via --deploymentId; no get), deployment-data-sources (same), and read-only workflow-jobs (list/get/traces/delete).

Notes:

• agent create requires --skillName (the only field required by CreateAgentDto); other sub-resource required fields are enforced by the backend.
• Convenience flags map 1:1 onto the matching CreateDto/UpdateDto snake_case keys; the agent DTO is large, so its flags are a curated subset — the long tail (compaction_, output_, prompt_*, …) and any nested arrays go through --data/--from-file.
• createOnly fields (e.g. --tenantDataSourceId, agent-tool --coreAiToolId) appear only on create; updateOnly fields (e.g. --archived) only on update. incur rejects unknown flags, so passing the wrong one fails before any request.
• delete returns a { deleted: true, id } envelope.

Messaging (messaging)

List tenant email accounts and send transactional emails. Routes through /v1/messaging/email/*. Requires the Messaging.Email.Send OAuth2 scope.

docyrus messaging accounts --json
docyrus messaging email send \
  --accountId <accountUuid> \
  --to "ops@example.com,sales@example.com" \
  --subject "Daily summary" \
  --body "<p>Hello</p>" --json

docyrus messaging email send --accountId <accountUuid> \
  --to "user@example.com" --cc "manager@example.com" --replyTo "support@example.com" --sendAsUser \
  --subject "Update" --body "<p>...</p>" --json

docyrus messaging email send --accountId <accountUuid> --from-file ./send.json --json

Limits: up to 50 recipients per to/cc/bcc/replyTo, subject max 998 chars, body max 1 000 000 chars, up to 10 attachments. Attachment filePath references a tenant-scoped storage path. The response contains messageId, provider, accepted, and rejected.

Connectors and Actions (connect)

Connectors are external integration providers (e.g. Meta WhatsApp, Microsoft Graph, Salesforce). Use connect to find connectors, inspect data sources/actions, check connection status, send provider-auth requests, and run actions.

# Discovery
docyrus connect list-connectors --q whatsapp --json
docyrus connect get-connector meta-whatsapp --json
docyrus connect get-action meta-whatsapp sendWhatsappMessage --json
docyrus connect list-connections meta-whatsapp --json

# Send requests through connector auth (OAuth tokens, base URL, API keys)
docyrus connect curl meta-whatsapp "433457363182570/phone_numbers" \
  -d '{"fields":"id,display_phone_number,verified_name"}' --json
docyrus connect curl meta-whatsapp "418088118057836/messages" -X POST \
  -d '{"messaging_product":"whatsapp","to":"905551234567","type":"template","template":{"name":"sample_template","language":{"code":"en_US"}}}' \
  --contentType "application/json" --json

# Run a connector action directly by provider slug + action key (POST /v1/connectors/:slug/actions/:actionKey/run)
docyrus connect run-action meta-whatsapp sendWhatsappMessage --params '{"to":"905551234567","templateName":"hello_world"}' --json
docyrus connect run-action meta-whatsapp sendWhatsappMessage --params '{"to":"905551234567"}' --dryRun --json

Aliases: connect curl — -X (method), -d (data), -c (connectionId). connect run-action — -p (params), -c (connectionId), -n (dryRun). connect curl data is sent as body for POST/PUT/PATCH and as query params for GET; --headers can override the Authorization header.

Arbitrary API Calls

docyrus curl /v1/users/me
docyrus curl /v1/apps -X GET --format json
docyrus curl /v1/some/endpoint -X POST -d '{"key":"value"}'

AI Agents and Dev Tooling

Beyond data operations, the CLI bundles the pi agent runtime and repo dev tooling. These are largely interactive or sandbox-runtime commands.

Chat and pi Agents

docyrus docy "Summarize open deals this month"       # one prompt to the platform's main AI agent
docyrus opsy                                          # launch the Cowork Agent (interactive TUI)
docyrus cody "fix the failing test in ds list"       # launch the Coding Agent (coder is an alias)
docyrus cody --print --mode json "list TODOs"        # one-shot, machine output

docy sends a single prompt (--agentId/--deploymentId optional); it renders markdown in a TTY and structured output with --json/--verbose/--format. opsy/cody/coder open the pi TUI by default, or run one-shot with --print; they accept --provider, --model, --thinking, --continue, --resume, --session, --apiKey, etc.

Agent Server

docyrus server --profile coder --port 3111

Starts an HTTP server bridging a pi agent to the AI SDK useChat protocol (SSE chat stream with reconnect/resume). Flags include --auth (require a bearer token), --sandbox (remote Cloudflare browser mode), and --desktop (expose docyrus_browser_* tools).

Browser Automation

docyrus browser start --profile
docyrus browser nav https://example.com
docyrus browser snapshot                 # compact element refs (@e1 …) for interaction
docyrus browser click @e3
docyrus browser fill @e5 "hello"
docyrus browser screenshot --full
docyrus browser content https://example.com   # extract readable markdown
docyrus browser close

Runs against local Chrome (:9222) or a remote Cloudflare session. Other subcommands: eval, select, wait, tabs, cookies, console, network, info, devtools, run-script.

Repo Knowledge Graph and Project Plan

docyrus knowledge search "how does auth refresh work"
docyrus knowledge section <sectionId>
docyrus knowledge check                      # validate links/backlinks
docyrus project-plan show
docyrus project-plan list-tasks --status in_progress --limit 5
docyrus project-plan set-task-status --taskId <id> --status done

knowledge manages the repo's docyrus/knowledge graph (search, audit, refresh, pre-commit gates). project-plan manages a repo-tracked plan graph of phases, features, and tasks (token-efficient list/find/upsert/status commands). Both are local dev-workflow tools used by the pi agents.

Releases

docyrus release status
docyrus release new-version --bump minor --json
docyrus release new-version --version 1.2.0 --dryRun --json

Bumps the version, generates a changelog, optionally tags, creates a GitHub release, and records a DB release row (skip with --skip* flags).

Terminal UI

docyrus tui

Launches the OpenTUI interface (requires Bun). It reuses the existing CLI command graph.

Key Rules

• Settings are project-local by default in ./.docyrus/; use -g/--global for ~/.docyrus/. env which shows the resolved scope.
• The CLI uses named environments, not API_BASE_URL.
• Flags accept both kebab-case (--app-slug, as --help prints) and camelCase (--appSlug, the schema key). --from-file reads JSON (and CSV for ds).
• Default login scopes are openid email profile offline_access ReadWrite.All Architect.ReadWrite.All Automations.Run Reports.Run.CustomQuery Messaging.Email.Send Messaging.Sms.Send Messaging.Whatsapp.Send MCP.Connect.
• Successful responses inject context (email, tenantName, tenantNo, tenantDisplay); it is null with no active session.
• apps list uses /v1/apps; apps mutations and set-agent-context/ai-tools use /v1/dev/apps/:appId.
• ds commands use appSlug and dataSourceSlug. ds create/update accept --data JSON or --from-file (.json/.csv), not both. Array payloads use bulk endpoints (max 50); bulk update requires id in each item and no positional <recordId>.
• ds list supports --columns (relation (), spread ..., alias :, function @), --filters (JSON filter group), --filterKeyword, --orderBy, --formulas, --calculations, --groupSummaries, --pivot, --childQueries, --expand, --distinctColumns, --collapseRows, --limit, --offset, --fullCount. Related-field filters use rel_<relation_slug>/<field_slug>.
• --format supports toon, json, yaml, md, and jsonl.
• Studio selectors are exclusive pairs: exactly one of --appId|--appSlug, --dataSourceId|--dataSourceSlug, and --fieldId|--fieldSlug as required. Studio write commands accept --data or --from-file (JSON only); explicit flags override overlapping JSON keys. restore-data-source/permanent-delete-data-source require --dataSourceId.
• Studio data-view/form commands route through /v1/apps/:appSlug/data-sources/:dataSourceSlug/...; webform/html-template/email-template commands route through /v1/dev/webforms, /v1/dev/html-templates, /v1/dev/email-templates (CRUD by --webformId/--templateId).
• automation routes through /v1/dev/apps/:appId/automations; trigger/node create/update use typed URLs (/triggers/<type>, /nodes/<type>), but delete-trigger/delete-node use the type-independent route. CLI flags are camelCase, converted to snake_case; nested objects go through --data/--from-file. automation create --triggerType is camelCase; trigger/node --type is kebab-case.
• agent commands route through /v1/dev/apps/:appId/agents...; the parent agent is --agentId and a sub-resource row is --id. agent create requires --skillName. createOnly/updateOnly flags are filtered per command.
• messaging routes through /v1/messaging/email/* and needs Messaging.Email.Send; accounts never returns credentials.
• connect uses the /v1/connectors API; connect curl sends through provider auth; connect run-action <providerSlug> <actionKey> is connector-scoped (POST /v1/connectors/:slug/actions/:actionKey/run). To run a persisted app action instead, use apps actions run (POST /v1/apps/:appSlug/actions/:actionId/run).
• tui requires Bun; docy/opsy/cody/coder/server run the pi agent runtime; knowledge/project-plan/release are repo dev-workflow tools.

References

• CLI Manifest — Complete command reference with flags, arguments, and command notes.
• List Query Examples — Practical ds list examples covering columns, filters, sorting, pagination, and advanced queries.