Docyrus CLI

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

Command Overview

Command	Description
docyrus	Show active environment, current auth context, and help summary
docyrus env list / env use	Manage named environments
docyrus auth login	Authenticate via OAuth2 device flow or manual tokens
docyrus auth logout	Logout the active account for the current environment
docyrus auth who	Show the active user and tenant
docyrus auth accounts list / use	Manage saved user accounts
docyrus auth tenants list / use	Manage saved tenants for a user
docyrus apps list	List apps from /v1/apps
docyrus ds get	Get data source metadata
docyrus ds list	Query records with filters, sorting, pagination
docyrus ds create / update / delete	Mutate records, including bulk create/update
docyrus studio ...	CRUD for dev app data sources, fields, and enums
docyrus discover api	Download tenant OpenAPI spec
docyrus discover namespaces / path / endpoint / entity / search	Explore the downloaded tenant OpenAPI spec
docyrus curl	Send arbitrary API requests
docyrus tui	Launch the OpenTUI terminal UI (requires Bun)

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.