docyrus-cli-app

What this skill does

# Docyrus CLI

Guide for using the `docyrus` CLI (`@docyrus/docyrus`) 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` / `env which` | Manage named environments and inspect resolved settings scope |
| `docyrus auth login` / `set-tokens` | Authenticate via OAuth2 device flow or manual tokens |
| `docyrus auth logout` / `who` / `tenant` | Logout the active account / show active user / show the current tenant record |
| `docyrus auth accounts list` / `use` | Manage saved user accounts |
| `docyrus auth tenants list` / `use` | Manage saved tenants for a user |
| `docyrus auth github` / `sandbox` / `sso-session` / `git-credential` | Sandbox/CI token helpers |
| `docyrus apps list` | List apps from `/v1/apps` |
| `docyrus apps update` / `delete` / `restore` / `permanent-delete` | Mutate apps via `/v1/dev/apps/:appId` |
| `docyrus apps set-agent-context` | Set an app's AI agent context |
| `docyrus apps actions ...` | CRUD app-scoped actions, list action types, and run an action |
| `docyrus apps ai-tools ...` | CRUD app-scoped AI tools |
| `docyrus ds get` / `list` | Read data source metadata and query records |
| `docyrus ds create` / `update` / `delete` | Mutate records, including bulk create/update |
| `docyrus ds comments create` / `files upload` | Add a record comment / upload a record file attachment |
| `docyrus studio ...` | CRUD dev app data sources, fields, enums, data views, forms, webforms, HTML/PDF/DOCX templates, email templates; search fields/enums/enum-sets |
| `docyrus automation ...` | CRUD automations, triggers, and action nodes for an app |
| `docyrus agent ...` | CRUD custom AI agents and their sub-resources (models, tools, data-sources, docs, mcps, connections, dynamic-contexts, tasks, recurring-tasks, workflow-steps, deployments, workflow-jobs) |
| `docyrus messaging accounts` / `email send` | List tenant email accounts / send transactional email |
| `docyrus connect ...` | Discover connectors, inspect actions, send provider-auth requests, run actions |
| `docyrus discover ...` | Download and explore the tenant OpenAPI spec |
| `docyrus curl` | Send arbitrary API requests |
| `docyrus docy "<prompt>"` | Chat with the platform's main AI agent |
| `docyrus opsy` / `cody` (`coder`) | Launch the pi Cowork / Coding agents (interactive TUI or one-shot) |
| `docyrus server` | Start the HTTP server bridging a pi agent to AI SDK `useChat` |
| `docyrus browser ...` | Browser automation (local Chrome or remote Cloudflare) |
| `docyrus knowledge ...` | Repo knowledge-graph search, audit, and maintenance |
| `docyrus project-plan ...` | Repo-tracked project plan graph (phases, features, tasks) |
| `docyrus release ...` | Version bump, changelog, and release record creation |
| `docyrus tui` | Launch the OpenTUI terminal UI (requires Bun) |

**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`

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

```bash
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:

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

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

```bash
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:

```bash
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:

```json
{
  "data": {},
  "context": {
    "email": "[email protected]",
    "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.

```bash
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

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

### Query Records (`ds list`)

Basic listing:

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

With filters:

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

With relation expansion:

```bash
docyrus ds list c