Docyrus Cli App

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](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](references/list-query-examples.md) for columns, filters, sorting, pagination, and advanced (formulas/calculations/pivot/child-query) examples.

Logical SQL (dsql)

dsql query runs a read-only PostgreSQL-compatible SELECT over logical tables named appSlug.dataSourceSlug. The SQL comes from the positional argument, --from-file, or stdin. Use the dsql schema commands first to discover queryable tables and columns.

docyrus dsql schema app base                       # schema for every data source in an app
docyrus dsql schema data-source base contact       # schema for one data source
docyrus dsql schema data-sources --ids ds-1,ds-2   # schema by data source ids
docyrus dsql query "select id, email from base.contact limit 100"
docyrus dsql query --from-file ./report.sql

Don't want to hand-write SQL? Let the DSQL generator agent do it:

docyrus dsql generate "top 10 contacts by revenue this year"   # returns the query text only
docyrus dsql ask "how many open tasks are assigned to me?"      # generates the query, runs it, returns rows

DSQL is a read-only PostgreSQL subset with a strict function allow-list, logical appSlug.dataSourceSlug tables, tenant.* identity/scope pseudo-functions, and built-in row-level security. See [references/dsql-reference.md](references/dsql-reference.md) for the full capability and limitation reference before writing non-trivial queries.

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 Create*Dto/Update*Dto 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](references/cli-manifest.md) — Complete command reference with flags, arguments, and command notes.
• [List Query Examples](references/list-query-examples.md) — Practical ds list examples covering columns, filters, sorting, pagination, and advanced queries.
• [DSQL Reference](references/dsql-reference.md) — Logical SQL (dsql query) capabilities and limits: table naming, allowed functions, tenant.* pseudo-functions, casts, row limits, access control, and the error catalog.

Docyrus CLI Manifest

LLM-ready reference for the docyrus CLI tool (@docyrus/docyrus). Generated from the live command graph (docyrus --llms).

---

Global Options

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

Environment Variables

Settings Scope

• Default scope is local: ./.docyrus/
• Use -g/--global for global scope: ~/.docyrus/
• Auth state: <settings-root>/auth.json
• Environment config: <settings-root>/config.json
• OpenAPI cache: <settings-root>/tenans/<tenantId>/openapi.json
• docyrus without a subcommand returns active environment, help commands, and auth context

Output Model

Every successful command injects a top-level context object (email, tenantName, tenantNo, tenantDisplay); it is null when there is no active session. Object payloads are merged with context; non-object payloads become { data, context }.

---

docyrus env

Environment commands.

docyrus env list

List available environments.

docyrus env use

Switch active environment by id or name.

docyrus env use <selector>

Built-in 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 env which

Show which environment is active for the current folder, plus the resolved settings scope (local/global), settingsRoot, configFilePath, authFilePath, cwd, and whether a local .docyrus/ exists.

---

docyrus auth

Authentication commands.

docyrus auth login

Authorize CLI using OAuth2 device flow, or provide tokens manually.

Default scope: 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

Login notes:

• Client ID resolution order: --clientId -> DOCYRUS_API_CLIENT_ID -> saved local config -> saved global config -> manual-token (manual-token auth only)
• Manual token login falls back to manual-token only when no client ID can be resolved
• Local login can reuse the globally saved client ID when local config has none

docyrus auth set-tokens

Set custom access and refresh tokens for the active environment. Same flags as auth login (--clientId, --scope, --accessToken, --refreshToken).

docyrus auth logout

Revoke and clear all tenant sessions for the active account in the current environment.

docyrus auth who

Return the current authenticated user (/v1/users/me).

docyrus auth tenant

Return the active tenant record (GET /v1/tenant/current). Read-only; no flags. Returns id, no, name, accountStatus, product/subscription refs, seat counts, paymentChannel, trial and subscription dates, and onboardingStatus. Distinct from the auth tenants (plural) account-management group.

docyrus auth accounts list

List saved user accounts for the current API base URL.

docyrus auth accounts use

Switch active account by user ID.

docyrus auth tenants list

List available tenants for an account.

docyrus auth tenants use

Switch active tenant for an account.

docyrus auth tenants use <tenantSelector> [options]

Selector rules: numeric -> match by tenantNo; non-numeric must be a UUID tenant id.

Sandbox / CI token helpers

Mostly invoked by the sandbox runtime; all default --appId to DOCYRUS_SANDBOX_APP_ID.

---

docyrus apps

App commands. list uses /v1/apps; mutations and AI sub-resources route through /v1/dev/apps/:appId. --appSlug resolution first consults the bundled SYSTEM/APP catalog, then falls back to GET /v1/apps.

docyrus apps list

List apps (/v1/apps).

docyrus apps update

PATCH /dev/apps/:appId. Store fields and array/object values must be supplied via --data/--from-file. An empty resulting payload is rejected.

docyrus apps set-agent-context

PATCH /dev/apps/:appId (agent_context). Provide exactly one of --value, --from-file, or --clear.

docyrus apps delete / restore / permanent-delete

Archive / restore / hard-delete an app.

docyrus apps ai-tools

CRUD over app-scoped tenant_ai_tool rows (/dev/apps/:appId/ai-tools). All commands take --appId/--appSlug.

• list — list AI tools for an app
• get / delete — --toolId
• create — --name and --key required
• update — --toolId plus changed fields

Create/update convenience flags: --name, --key, --description, --icon, --type, --clientSideExecution, --needsApproval, --environments (CSV), --dynamicApprovalFormula, --inputJsonSchema (JSON), --outputJsonSchema (JSON), --secureExecCode, --customQuerySqlQuery, --customQueryFilters (JSON), --dataSourceQueryDataSourceId, --dataSourceQueryColumns (JSON), --dataSourceQueryFilters (JSON), --dataSourceQueryFilterKeyword, --dataSourceQueryFormulas (JSON), --dataSourceQueryChildQueries (JSON), --dataSourceQueryLimit, plus --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 — the endpoint leaves them at their defaults.

docyrus apps actions

CRUD over standalone tenant_action rows (/dev/apps/:appId/actions), plus the action-type picker and run. All commands take --appId/--appSlug.

• list — list app actions
• types — list selectable action types (/dev/apps/:appId/actions/types); excludes client-only and automation-flow-only actions (create/update record, wait-for); each row carries color (Tailwind color name)
• get / delete — --actionId
• create — --name and --coreActionId required (--coreActionId is create-only / immutable)
• update — --actionId plus changed fields (--coreActionId is rejected)
• run — --actionId; posts the body as the action input record to the slug-based public endpoint POST /v1/apps/:appSlug/actions/:actionId/run (accepts --appId, reverse-resolved to the slug); body via --data/--from-file (an empty body is allowed)

Create/update convenience flags: --name, --coreActionId (create only), --status, --options (JSON), --conditions (JSON), --sourceDataSourceId, --inputDataSourceId, --targetDataSourceId, --targetDataSourceFieldId, --targetDataSourceCondition (JSON), --connectionId, --connectionAccountId, --webhookId, --requestMethod, --contentType, --customEndpoint, --relativeEndpoint, --batch, --batchSize, --customHeaders (JSON), --inputTransformer (JSON), --outputTransformer, --batchTransformer, --errorTransformer, --inputTemplate (JSON), --preActionRequest (JSON), --postActionRequest (JSON), --inputJsonSchema (JSON), --outputJsonSchema (JSON), plus --data/--from-file.

---

docyrus ds

Data source commands for CRUD on records.

docyrus ds get

Get data source metadata (fields, types, relations).

docyrus ds get <appSlug> <dataSourceSlug>

docyrus ds list

List data source items with the full query engine.

docyrus ds list <appSlug> <dataSourceSlug> [options]

docyrus ds create

Create item(s). Array payload triggers POST /apps/:appSlug/data-sources/:dataSourceSlug/items/bulk (max 50 items).

docyrus ds create <appSlug> <dataSourceSlug> [options]

docyrus ds update

Update item(s). Object payload uses the single-item endpoint and requires recordId; array payload uses the bulk endpoint, requires id in each item, and must not include positional recordId. Max 50 per batch.

docyrus ds update <appSlug> <dataSourceSlug> [recordId] [options]

docyrus ds delete

Delete an item.

docyrus ds delete <appSlug> <dataSourceSlug> <recordId>

docyrus ds comments create

Create a record-scoped comment.

docyrus ds comments create <appSlug> <dataSourceSlug> <recordId> [options]

docyrus ds files upload

Upload a record-scoped file attachment (multipart/form-data).

docyrus ds files upload <appSlug> <dataSourceSlug> <recordId> [options]

---

docyrus dsql

Run read-only logical SQL queries and inspect the token-efficient DSQL schema. Logical tables are named appSlug.dataSourceSlug (e.g. base.contact). Requires DS.Read.* / DS.ReadWrite.* scopes.

docyrus dsql query

Run a read-only PostgreSQL-compatible SELECT over logical data-source tables (PUT /dsql/query). The SQL is resolved from the positional argument, --from-file, or stdin (in that order). Throttled to 60 requests/minute.

docyrus dsql query "select id, email from base.contact limit 100"
docyrus dsql query --from-file ./report.sql
echo "select count(*) from base.task" | docyrus dsql query

Returns { data: [...], meta: { count } }.

docyrus dsql generate

Generate a DSQL query from a natural-language question using the base DSQL generator agent (POST /ai/agents/:agentId/chat). Returns the query text only — it does not run it. The question is resolved from the positional argument, --from-file, or stdin.

docyrus dsql generate "top 10 contacts by revenue this year"
docyrus dsql generate --from-file ./question.txt

The agent returns structured output: { prompt, query } (it echoes a normalized prompt alongside the generated query).

docyrus dsql ask

Generate a DSQL query from a natural-language question, then run it through PUT /dsql/query and return the rows. Combines generate + query.

docyrus dsql ask "how many open tasks are assigned to me?"

Returns { prompt, query, data: [...], meta: { count } }.

docyrus dsql schema app

Return the DSQL schema for every queryable data source in an app (GET /dsql/schema/apps/:appSlug).

docyrus dsql schema app base

docyrus dsql schema data-source

Return the DSQL schema for a single data source (GET /dsql/schema/apps/:appSlug/data-sources/:dataSourceSlug).

docyrus dsql schema data-source base contact

docyrus dsql schema data-sources

Return the DSQL schema for the data sources matching the given ids (GET /dsql/schema/data-sources?ids=...).

docyrus dsql schema data-sources --ids ds-1,ds-2

---

docyrus studio

Dev-app schema CRUD. Data-source/field commands route through /v1/dev/apps/:appId/data-sources...; 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.

Selector rules:

• app selector: exactly one of --appId or --appSlug
• data source selector: exactly one of --dataSourceId or --dataSourceSlug when required
• field selector: exactly one of --fieldId or --fieldSlug when required

Write payload rules:

• use --data '<json>' or --from-file ./payload.json (JSON only), not both
• flags override conflicting keys from the JSON payload
• batch commands accept a root array or a root object containing the expected DTO key

Data source commands

Field commands

The CLI normalizes common live-output shapes before sending batches: id -> fieldId, id -> enumId, read_only -> readOnly, default_value -> defaultValue, relation_data_source_id -> relationDataSourceId, options -> editorOptions.

Enum commands

Search commands (tenant-wide, paged)

Data view commands

Route through /v1/apps/:appSlug/data-sources/:dataSourceSlug/views. Pass either --appId/--appSlug and either --dataSourceId/--dataSourceSlug; the CLI resolves the missing side.

Form commands

Route through /v1/apps/:appSlug/data-sources/:dataSourceSlug/forms.

Webform commands

Route through /v1/dev/webforms. CRUD by --webformId. List/create accept --dataSourceId, or --dataSourceSlug with --appId/--appSlug to resolve. When dataSourceId is omitted on create, submissions land in the tenant-schema webform_record table.

HTML template commands (HTML / PDF / DOCX export)

Route through /v1/dev/html-templates. CRUD by --templateId. Data source binding by --dataSourceId or --dataSourceSlug (slug requires --appId/--appSlug).

Email template commands

Route through /v1/dev/email-templates. CRUD by --templateId. Data source binding optional.

---

docyrus automation

Automation, trigger, and action node CRUD. Routes through /v1/dev/apps/:appId/automations.

Selector rules:

• app selector: exactly one of --appId or --appSlug
• automation selector: --automationId only (no slug)
• trigger --type (kebab-case): record-created, record-modified, record-deleted, recurrence, app-event, webhook, emailhook, webform, button-activation, manual-activation
• node --type (kebab-case): 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

Write payload rules:

• write commands accept --data '<json>' or --from-file ./payload.json (JSON only)
• convenience flags are camelCase and converted to snake_case
• nested objects (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
• delete, delete-trigger, delete-node return { deleted: true, id } (API returns 204)

Automation CRUD

Trigger commands

list-triggers / get-trigger are derived from the automation GET response. create-trigger/update-trigger route through POST|PATCH .../triggers/:type[/ :triggerId]; delete-trigger routes through DELETE .../triggers/:triggerId (type-independent).

create-trigger flags (--automationId, --type required):

update-trigger adds --triggerId (required). delete-trigger takes --automationId and --triggerId.

Action node commands

list-nodes (GET .../nodes), get-node (GET .../nodes/:nodeId). create-node/update-node route through POST|PATCH .../nodes/:type[/ :nodeId]; delete-node routes through DELETE .../nodes/:nodeId (type-independent).

create-node flags (--automationId, --type required):

update-node adds --nodeId (required). delete-node takes --automationId and --nodeId.

Notes:

• external-action create validates data against the linked core_action.input_json_schema and creates the tenant_action row in the same transaction.
• wait-for takes no flat flags beyond the common base. Set the delay inside data: delaySeconds (integer ≤ 30 days / 2_592_000) or delayValue + delayUnit (seconds/minutes/hours/days). It forwards input unchanged and queues next step(s) with a deferred tenant_job_queue.process_after.

docyrus automation create-node \
  --appSlug crm --automationId 9c4f… \
  --type wait-for --name "Wait 2 hours" --parent <previous-node-id> \
  --data '{"data":{"delayValue":2,"delayUnit":"hours"}}'

---

docyrus agent

Custom-agent CRUD for the dev controller (/v1/dev/apps/:appId/agents...). Distinct from the pi-agent launchers (opsy/cody/coder).

Selector and payload rules:

• app selector: exactly one of --appId or --appSlug
• the parent agent is --agentId; an individual sub-resource row is --id
• create/update accept --data/--from-file (JSON) plus camelCase convenience flags that map 1:1 onto the matching Create*Dto/Update*Dto snake_case keys
• JSON flags are parsed from JSON; list flags (e.g. --standardSuggestions, --supportedFileFormats, --ownerProductId) are comma-separated arrays
• createOnly fields appear only on create; updateOnly fields (e.g. --archived) only on update; incur rejects unknown flags
• delete returns { deleted: true, id }

Agent resource

create/update convenience flags: --name, --agentName, --skillName, --description, --category, --mode, --instructions, --welcomeMessage, --defaultAiModelId, --backupAiModelId, --cotAiModelId, --defaultReasoningLevel, --parent, --ownership (SYSTEM/APP/TENANT), --tenantAppId, --workDataSourceId, --status, --developmentStatus, --sortOrder, --temperature, --maxTokens, --isAgent, --isAssistant, --isSkill, --jsonOutput, --hasWorkflow, --multipleDeployment, --supportTools, --supportDataSources, --supportFiles, --supportKnowledgeBase, --supportWebSearch, --standardSuggestions (CSV), --supportedFileFormats (CSV), --ownerProductId (CSV), --instructionSchema (JSON), --inputFormSchema (JSON), --outputRenderSchema (JSON), --memoryOptions (JSON), --helpDocs (JSON), plus --data/--from-file. The long tail (compaction_*, context_clear_*, output_*, prompt_*, …) goes through --data/--from-file.

Sub-resource groups

Each group supports list/get/create/update/delete (unless noted). All take --appId/--appSlug and --agentId; row commands take --id. Key create flags shown.

---

docyrus messaging

Tenant email account discovery and transactional email send. Routes through /v1/messaging/email/*. Requires the Messaging.Email.Send OAuth2 scope. Credentials are never returned.

docyrus messaging accounts

GET /messaging/email/accounts. Each account exposes id, name, provider, senderEmail, senderName, isUserAccessible, allowOverrideName, allowOverrideEmail, createdOn.

docyrus messaging email send

POST /messaging/email/accounts/:accountId/send

Limits: up to 50 addresses per list, up to 10 attachments. Attachments are { filePath, fileName?, mimeType? } referencing tenant-scoped storage paths. Response: { messageId, provider, accepted, rejected }.

---

docyrus connect

Connector and action commands.

docyrus connect list-connectors

docyrus connect get-connector / get-action / list-connections

docyrus connect get-connector <slug>
docyrus connect get-action <slug> <actionKey>
docyrus connect list-connections <slug>

get-connector returns data sources + actions; get-action returns input/output JSON schemas; list-connections returns tenant and user connections.

docyrus connect curl

Send an HTTP request through a connector's provider auth.

docyrus connect curl <slug> <endpoint> [options]

docyrus connect run-action

Run a connector action directly by provider slug + action key via POST /v1/connectors/:slug/actions/:actionKey/run. (To run a persisted app action, use apps actions run.)

docyrus connect run-action <slug> <actionKey> [options]

---

docyrus discover

Discovery commands for the tenant OpenAPI spec. All require an active login session. Commands other than discover api auto-download the spec if missing locally (public bucket -> authenticated GET /v1/api/openapi.json -> public retry).

---

docyrus curl

Send arbitrary requests to the Docyrus API.

docyrus curl <path> [options]

Notes: path-only (no absolute URLs); /v1 prefix auto-normalized; JSON payloads auto-detect Content-Type: application/json; default method GET (POST if -d provided).

---

docyrus docy

Chat with the platform's main AI agent.

docyrus docy "<prompt>"

Renders markdown in a TTY; preserves structured output with --json/--verbose/--format.

---

docyrus opsy / cody / coder (pi agents)

Launch the pi agent runtime. opsy = Cowork Agent; cody = Coding Agent (coder is an alias of cody). Each takes an optional prompt argument (omit to open the interactive TUI).

---

docyrus server

Start an HTTP server bridging a pi agent to the AI SDK useChat protocol (SSE chat stream with reconnect/resume).

---

docyrus browser

Browser automation (local Chrome on :9222 or remote Cloudflare). Commands return JSON with a mode field.

---

docyrus knowledge

Repo knowledge-graph commands operating on docyrus/knowledge. Local dev-workflow tooling.

---

docyrus project-plan

Repo-tracked project plan graph (phases -> features -> tasks). Token-efficient list/find/upsert/status commands. Local dev-workflow tooling.

---

docyrus release

Release and versioning commands.

docyrus release status

Show current release status and unreleased changes.

docyrus release new-version

Create a new release with version bump, changelog generation, and optional GitHub release.

---

docyrus tui

Launch the OpenTUI terminal UI.

Notes:

• requires Bun installed locally
• reuses the existing CLI command graph
• intended for interactive terminal usage rather than browser embedding

DSQL Reference — Capabilities, Limitations & Pseudo-Functions

DSQL (Docyrus Structured Query Language) is a read-only, PostgreSQL-compatible SQL dialect that runs over logical data-source tables instead of physical tables. You write SELECT queries against logical names like base.contact, and the engine resolves them to the correct tenant schema, applies row-level access control, and enforces a strict allow-list of statements and functions.

This reference documents exactly what DSQL supports and rejects. It is derived from the engine implementation (LogicalSqlQueryRunner, DsqlSchema, DsqlAccessPlanner), not from generic Postgres behavior — where the two differ, this file is authoritative.

Run DSQL from the CLI:

```bash

docyrus dsql query "select id, email from base.contact limit 100"

docyrus dsql query --from-file ./report.sql

docyrus dsql schema app base # discover queryable tables + columns

docyrus dsql schema data-source base contact

docyrus dsql schema data-sources --ids ds-1,ds-2

```

Always discover the schema first — never guess table or field slugs.

>

Not sure how to write the SQL? docyrus dsql generate "<question>" turns a natural-language question into a DSQL query via the DSQL generator agent, and docyrus dsql ask "<question>" generates it and runs it in one step. The agent follows every rule in this document.

---

1. Logical table naming

Tables are addressed as `appSlug.dataSourceSlug` (schema-qualified logical names). Unqualified table names are rejected unless they are a CTE alias.

select * from base.task t
select * from crm.contact c
select * from custom.my_source s

Physical resolution (informational — you never write these): global datasets map to the dataset schema, SYSTEM data sources to public, everything else to the tenant's private schema.

External data sources cannot be queried — any source backed by an external SQL provider is rejected with External data source '…' is not supported by the SQL query endpoint.

Child / inherited sources

Some data sources inherit fields from a parent ("base") source. You query the child logical source directly; when you reference an inherited (base) field, the engine auto-injects a LEFT JOIN to the base table on base.id = child.id. You do not write that join yourself.

• A child whose base is a simple-type source is not queryable (Simple base data source '…' is not supported).

---

2. Field referencing

Reference fields by logical field slug, in one of three forms (resolved in this order):

• `id` is always available on every logical source (a synthetic UUID is provided if the source has no natural id). For tenant.user, id is the user's id.
• Simple-source custom fields are stored internally in a JSONB data column but are exposed as regular columns by slug — query s.amount, not s.data->'amount'.
• Virtual / computed field types are NOT queryable and are omitted from the schema: field-list, field-display, field-formula, field-taskList, field-button. Referencing one throws Field '…' is not supported by the SQL query endpoint.
• Internal columns are hidden and not selectable: tenant_id, tenant_data_source_id, cursor_date, sort_order, style, docyment, parent_data_source_id, parent_record_id, editor_view_id, followers, mentions (and the raw data column on simple sources).

---

3. Supported SQL surface

DSQL accepts exactly one read-only `SELECT` statement. Within that statement you may use:

• SELECT (including DISTINCT), FROM, WHERE, GROUP BY, HAVING, ORDER BY, LIMIT, OFFSET
• Joins: INNER, LEFT, RIGHT, FULL, CROSS, plus implicit joins via WHERE
• CTEs (WITH …) — read-only only
• Subqueries in SELECT, WHERE, and FROM (a FROM subquery must be aliased)
• Set operations: UNION / UNION ALL / INTERSECT / EXCEPT (each side is itself a validated SELECT)
• Aggregates and GROUP BY / HAVING
• ORDER BY may reference a SELECT-list alias
• Type casts with ::type (see §6)

SELECT * is allowed but must be unambiguous: with more than one source in FROM, qualify it (t.*), and * may only appear in the SELECT list.

---

4. Hard restrictions

Rejected at parse/compile time (before any execution):

• Only `SELECT`. Every non-select statement type is blocked: INSERT, UPDATE, DELETE, MERGE, CALL, DO, all CREATE*/ALTER*/DROP*, TRUNCATE, COPY, GRANT, INDEX, VACUUM, SET/SHOW, NOTIFY/LISTEN, BEGIN/COMMIT (transactions), and EXPLAIN.
• Exactly one statement — no multiple semicolon-separated statements.
• No `SELECT INTO`.
• No data-modifying CTEs (a WITH branch that is anything other than a SELECT).
• No functions/`LATERAL` in `FROM` (Functions in FROM are not supported). Set-returning functions as a table source are not allowed.
• No unqualified physical/table names — only appSlug.dataSourceSlug logical names (or CTE aliases).
• *No `pg_ functions** and no access to physical tenant schemas or public` tables directly.
• Read-only execution: the query runs inside a readOnly transaction with a 15-second statement timeout.

---

5. Supported functions (allow-list)

Only the functions below may be called. Names are matched case-insensitively. Anything else throws Function '…' is not supported.

String length, lower, upper, substr, replace, concat, trim, ltrim, rtrim, btrim, split_part, initcap, reverse, strpos, lpad, rpad

Number abs, ceil, floor, round, sqrt, power, mod, gcd, lcm, exp, ln, log, log10, log1p, pi, sign, width_bucket, trunc, greatest, least

Date / time now, age, clock_timestamp, date_part, date_trunc, extract, isfinite, justify_days, justify_hours, make_date, make_time, make_timestamp, make_timestamptz, timeofday, to_timestamp, to_char, to_date, to_time

JSON / JSONB jsonb_array_length, jsonb_extract_path, jsonb_extract_path_text, jsonb_object_keys, jsonb_build_object, json_build_object, array_to_json, row_to_json

Utility coalesce

Aggregates (callable as aggregates only) count, sum, avg, min, max, array_agg, json_agg, jsonb_agg

Allowed bare literals: current_date, current_time, current_timestamp.

Not supported (common surprises)

• Window functions: dedicated window functions (row_number, rank, dense_rank, lead, lag, ntile, first_value, …) are not on the allow-list and are rejected. Do not rely on OVER (…) windowing — it is outside the supported surface.
• Explicitly blocked: current_setting, set_config, version, pg_sleep, pg_read_file, pg_read_binary_file, inet_server_addr, inet_server_port, and everything prefixed `pg_`.
• Anything not in the lists above (e.g. string_agg, regexp_replace, position, left/right, nullif, case-as-function, generate_series) — if you need it, restructure the query or post-process the result.
• Schema-qualified function calls are only allowed as pg_catalog.<name> (and still must resolve to an allow-listed name).

---

6. Type casts

::type casts are restricted to this set (scalar and [] array variants):

int, int2, int4, int8, bigint, real, float, float4, float8, numeric, decimal, double, money, timestamp, timestamptz, date, time, interval, bool, boolean, uuid, text

---

7. tenant.* pseudo-functions

These are DSQL-only helpers (not real Postgres functions) that inject the current user's identity and organizational scope into your query. They are translated to SQL at compile time. Use them in WHERE/SELECT to write permission- and org-aware queries. Each takes 0 or 1–2 UUID arguments as shown; an argument-count mismatch throws tenant.X expects N argument(s).

Identity & context (no args)

User matching (1 arg → boolean)

Scope membership (1 arg → boolean)

Role membership

Team membership

Hierarchy-unit membership

---

8. Limits & execution

• If you omit LIMIT, the engine wraps the query and applies the default. If you request more than the cap, it is silently clamped to the cap. LIMIT ALL or a non-literal limit falls back to the default. Negative LIMIT is rejected.
• For totals/aggregates, do the aggregation in SQL (count, sum, …) rather than fetching rows and counting client-side.

---

9. Access control & scopes

DSQL enforces the same row-level security as the rest of the platform — you only ever see rows you are permitted to see.

• Business sources (any app slug other than core/tenant) require a view ACL for the current user's roles; otherwise the query fails with 403 `Access denied to logical data source '…'`. Role-restriction queries (hidden-level restrictions) and child-relation filters are injected automatically.
• `PRIVATE` data-access sources require a record_owner field and limit visibility to the owner and their hierarchy subordinates (gated by the source's unit-peer-access level).
• `core`/`tenant` sources skip source ACL but still apply tenant scoping.

OAuth scopes (when called with an app/API token):

• DS.Read.All or DS.ReadWrite.All → all data sources.
• Per-source: DS.Read.{Slug} or DS.ReadWrite.{Slug}, where {Slug} is the PascalCase of appSlug_dataSourceSlug (e.g. base.contact → DS.Read.BaseContact).
• Delegated user-context tokens (openid/profile/email/offline_access) are not subject to the per-source scope gate.
• A missing scope throws an insufficient-scope error listing the scope(s) required.

The CLI docyrus dsql commands send the active session's token, so interactive limits (max 1,000 rows) and delegated-scope rules apply.

---

10. Error catalog & recovery

All DSQL errors are QueryBuilderErrors (HTTP 400 unless noted). Common ones and how to fix:

When a query fails: read the message, fix against the schema and the rules above, and retry. If it suggests a wrong source/field, go back to dsql schema … discovery.

---

11. Patterns

-- Resolve owner name/email via tenant.user
select t.id, t.title, u.full_name as owner
from base.task t
left join tenant.user u on u.id = t.record_owner
order by t.created_on desc
limit 50;

-- Resolve a status enum label/color via tenant.enum
select c.id, c.name, e.name as status_label, e.color
from crm.contact c
left join tenant.enum e on e.id = c.status;

-- Status breakdown, aggregated in SQL
select e.name as status, count(*) as total
from base.task t
left join tenant.enum e on e.id = t.status
group by e.name
order by total desc;

-- "My records" using identity pseudo-functions
select t.id, t.title
from base.task t
where tenant.is_current_user(t.record_owner)
limit 100;

-- Records owned by anyone in the current user's hierarchy scope
select t.id, t.title, t.record_owner
from base.task t
where tenant.in_current_user_scope(t.record_owner);

---

12. Differences from standard PostgreSQL (gotchas)

• You query logical names (appSlug.dataSourceSlug), never physical tables. Bare/unqualified table names are rejected.
• The function surface is a strict allow-list — many everyday Postgres functions (window functions, string_agg, regexp_*, nullif, left/right, position, generate_series) are unavailable.
• id is guaranteed on every source; the physical user_id on tenant.user is hidden behind id.
• Virtual/computed Docyrus fields don't exist as columns.
• Every query is implicitly row-level-secured and clamped by a LIMIT cap; "see everything" is not possible.
• tenant.* are pseudo-functions, not real functions — they only work inside DSQL.

List Query Examples

Practical examples for docyrus ds list with columns, filters, sorting, pagination, and the advanced query engine (keyword search, calculations, formulas, pivots, child queries).

JSON flags (--filters, --calculations, --formulas, --pivot, --childQueries, etc.) take the same payload shapes the /items query endpoint accepts. For the full payload reference see the docyrus-platform skill's data-source-query-guide.md.

---

Table of Contents

1. Basic Listing 2. Column Selection 3. Filtering 4. Sorting 5. Pagination 6. Combined Examples 7. Advanced Queries

---

Basic Listing

List all records with default columns:

docyrus ds list crm contacts

List with JSON output:

docyrus ds list crm contacts --format json

---

Column Selection

Select specific fields:

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

Select with relation expansion (get related account's name):

docyrus ds list crm contacts --columns "name, email, related_account(account_name)"

Spread related fields into root object:

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

Alias columns:

docyrus ds list crm contacts --columns "n:name, e:email, p:phone"

---

Filtering

Single field equals

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

Multiple conditions (AND)

docyrus ds list crm contacts --filters '{"combinator":"and","rules":[{"field":"status","operator":"=","value":"active"},{"field":"priority","operator":">=","value":3}]}'

OR conditions

docyrus ds list crm contacts --filters '{"combinator":"or","rules":[{"field":"city","operator":"=","value":"Istanbul"},{"field":"city","operator":"=","value":"Ankara"}]}'

IN operator (match any value in list)

docyrus ds list crm contacts --filters '{"rules":[{"field":"status","operator":"in","value":[1,2,3]}]}'

Not equal

docyrus ds list crm contacts --filters '{"rules":[{"field":"status","operator":"!=","value":"archived"}]}'

Text search with LIKE

docyrus ds list crm contacts --filters '{"rules":[{"field":"name","operator":"like","value":"John"}]}'

Empty / not empty

docyrus ds list crm contacts --filters '{"rules":[{"field":"email","operator":"not empty"}]}'

docyrus ds list crm contacts --filters '{"rules":[{"field":"phone","operator":"empty"}]}'

Date shortcuts

Records created this month:

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

Records created today:

docyrus ds list crm contacts --filters '{"rules":[{"field":"created_on","operator":"today"}]}'

Records from last 30 days:

docyrus ds list crm contacts --filters '{"rules":[{"field":"created_on","operator":"last_30_days"}]}'

Date range with between

docyrus ds list crm contacts --filters '{"rules":[{"field":"created_on","operator":"between","value":["2025-01-01","2025-06-30"]}]}'

Filter on related field

Filter by related account's status:

docyrus ds list crm contacts --filters '{"rules":[{"field":"rel_related_account/account_status","operator":"=","value":1}]}'

Current user filter

Records owned by current user:

docyrus ds list crm contacts --filters '{"rules":[{"field":"record_owner","operator":"active_user"}]}'

Nested AND + OR

Active contacts created this month OR contacts with high priority:

docyrus ds list crm contacts --filters '{"combinator":"or","rules":[{"combinator":"and","rules":[{"field":"status","operator":"=","value":"active"},{"field":"created_on","operator":"this_month"}]},{"field":"priority","operator":">=","value":5}]}'

---

Sorting

Sort by name ascending (default):

docyrus ds list crm contacts --orderBy "name"

Sort by created date descending:

docyrus ds list crm contacts --orderBy "created_on DESC"

---

Pagination

First 10 records:

docyrus ds list crm contacts --limit 10

Next 10 records (page 2):

docyrus ds list crm contacts --limit 10 --offset 10

Get total count alongside results:

docyrus ds list crm contacts --limit 10 --fullCount true

---

Combined Examples

Active contacts with email, sorted by name, paginated

docyrus ds list crm contacts \
  --columns "name, email, phone, created_on" \
  --filters '{"rules":[{"field":"status","operator":"=","value":"active"},{"field":"email","operator":"not empty"}]}' \
  --orderBy "name" \
  --limit 25 \
  --fullCount true

Recent high-priority deals with account info

docyrus ds list crm deals \
  --columns "name, amount, stage, ...related_account(account_name)" \
  --filters '{"combinator":"and","rules":[{"field":"priority","operator":">=","value":4},{"field":"created_on","operator":"last_30_days"}]}' \
  --orderBy "amount DESC" \
  --limit 20

Search for records by keyword

docyrus ds list crm contacts \
  --columns "name, email, phone" \
  --filters '{"rules":[{"field":"name","operator":"like","value":"Smith"}]}' \
  --format json

Export all records as JSON lines

docyrus ds list crm contacts \
  --columns "id, name, email, phone, status, created_on" \
  --format jsonl

Records owned by current user, created this quarter

docyrus ds list crm tasks \
  --columns "name, status, priority, due_date" \
  --filters '{"combinator":"and","rules":[{"field":"record_owner","operator":"active_user"},{"field":"created_on","operator":"this_quarter"}]}' \
  --orderBy "due_date" \
  --limit 50

---

Advanced Queries

Keyword search

Full-text keyword filter across searchable fields:

docyrus ds list crm contacts --columns "name, email" --filterKeyword "renewal"

Calculations (aggregations / group-by)

Group by a column (via --columns) and aggregate with --calculations. Each rule is { field, func, name, isDistinct? } (func: count, sum, avg, min, max). Add --groupSummaries to include per-group summary rows.

# Count open tasks per owner
docyrus ds list crm tasks \
  --columns "record_owner(name)" \
  --calculations '[{"field":"id","func":"count","name":"open_tasks"}]' \
  --filters '{"rules":[{"field":"task_status","operator":"=","value":1}]}' --json

# Multiple aggregations per category, with group summaries
docyrus ds list crm deals \
  --columns "category" \
  --calculations '[{"field":"id","func":"count","name":"total"},{"field":"amount","func":"sum","name":"totalAmount"},{"field":"amount","func":"avg","name":"avgAmount"}]' \
  --groupSummaries --json

# Distinct count
docyrus ds list crm contacts \
  --calculations '[{"field":"email","func":"count","name":"unique_emails","isDistinct":true}]' --json

Formulas (computed columns)

--formulas is a { name: definition } object; each name must also appear in --columns.

# Inline math formula
docyrus ds list crm accounts \
  --columns "id, name, balance_pct" \
  --formulas '{"balance_pct":{"inputs":[{"kind":"math","op":"/","inputs":[{"kind":"column","name":"balance"},{"kind":"literal","literal":100}]}]}}' --json

# Subquery formula (count child records)
docyrus ds list crm accounts \
  --columns "id, name, contacts_count" \
  --formulas '{"contacts_count":{"from":"crm_contacts","with":"account","inputs":[{"kind":"aggregate","name":"count","inputs":[]}]}}' --json

Pivot

--pivot builds a matrix of cross-joined dimensions left-joined onto the main query, so every combination appears even with zero matches.

docyrus ds list crm orders \
  --columns "...order_status(orderStatus:name)" \
  --pivot '{"matrix":[{"using":"created_on","columns":"day:to_char[DD/MM/YYYY]@created_on","dateRange":{"interval":"day","min":"2025-09-01T00:00:00Z","max":"2025-09-30T00:00:00Z"},"spread":true}]}' --json

Child queries (nested records)

--childQueries embeds related rows under an alias that must also appear in --columns. Each entry is { alias, from, using, columns?, filters?, calculations?, orderBy?, limit? }; from uses appSlug_slug and using is the child field referencing the parent id.

docyrus ds list crm accounts \
  --columns "id, name, recent_deals" \
  --childQueries '[{"alias":"recent_deals","from":"crm_deals","using":"account","columns":"name, amount","orderBy":"created_on DESC","limit":5}]' --json

Expand and distinct columns

# Expand related/nested columns
docyrus ds list crm contacts --columns "name, email" --expand "related_account" --json

# Deduplicate rows by selected columns (e.g. one row per email)
docyrus ds list crm contacts --columns "email, name, created_on" --distinctColumns "email" --json