Docyrus CLI

Guide for using the docyrus CLI to interact with the Docyrus platform from the terminal.

Command Overview

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

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

Examples:

# 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"

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 -> https://localhost:3366

Examples:

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:

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

Rules:

• --refreshToken requires --accessToken
• if local login omits --clientId, the CLI falls back to the saved global client ID when available
• explicit or previously resolved client IDs are saved to config for reuse
• default scopes are hardcoded in the CLI and include openid, email, profile, offline_access, ReadWrite.All, User.ReadWrite, Users.Read.All, Tenant.Read, Teams.Read.All, DS.ReadWrite.All, Docs.ReadWrite.All, and Architect.ReadWrite.All

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

auth tenants use takes a positional tenant selector. If it is numeric, the CLI treats it as tenantNo; otherwise it must be a UUID tenant ID.

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)"

Date shortcut filter:

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

See references/list-query-examples.md for more filter, sort, pagination, and combined query examples.

Record Mutations

Create:

docyrus ds create crm contacts --data '{"name":"Jane Doe","email":"jane@example.com"}'

Update:

docyrus ds update crm contacts <recordId> --data '{"phone":"+1234567890"}'

Delete:

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.

Studio Schema CRUD (studio)

Use studio for developer-facing schema operations under /v1/dev/apps/:app_id/data-sources.

# 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 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

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"}'

Terminal UI

Launch the OpenTUI interface:

docyrus tui

It requires Bun installed locally. The TUI reuses the existing CLI command graph.

Key Rules

• Settings are project-local by default in ./.docyrus/; use -g or --global for ~/.docyrus/
• The CLI uses named environments, not API_BASE_URL
• apps list uses /v1/apps
• ds commands use appSlug and dataSourceSlug
• ds create and ds update accept --data JSON or --from-file (.json or .csv), but not both
• Array payloads use bulk endpoints with a maximum of 50 items
• Bulk update requires id in every item and must not include positional <recordId>
• --filters accepts a JSON filter group such as {"combinator":"and","rules":[...]}
• Related-field filters use rel_<relation_slug>/<field_slug>
• --columns supports relation expansion (), spread ..., aliasing :, and functions @
• --format supports toon, json, yaml, md, and jsonl
• Successful responses inject context with email, tenantName, tenantNo, and tenantDisplay
• 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), and explicit flags override overlapping JSON keys

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 combined queries.