@docyrus/docyrus 0.0.16 → 0.0.17

package/resources/pi-agent/skills/docyrus-cli-app/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: docyrus-cli-app
+description: Use the Docyrus CLI (`docyrus`) to interact with the Docyrus platform from the terminal. Use when the user asks to authenticate, list apps, query or manage data records (`ds`), manage dev app data source schema objects (`studio`), send API requests, switch environments, tenants, or accounts, discover tenant OpenAPI specs, or use the Bun-powered terminal UI via `docyrus tui`. Triggers on tasks involving docyrus CLI commands, terminal-based Docyrus operations, `docyrus ds list`, `docyrus studio`, `docyrus discover`, `docyrus auth`, `docyrus env`, `docyrus tui`, or shell-based Docyrus workflows.
+---
+
+# 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](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:
+
+```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"
+```
+
+### 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:
+
+```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:
+
+```bash
+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:
+
+```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
+```
+
+`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:
+
+```json
+{
+  "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.
+
+```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 crm contacts \
+  --columns "name, ...related_account(account_name, account_phone)"
+```
+
+Date shortcut filter:
+
+```bash
+docyrus ds list crm tasks --filters '{"rules":[{"field":"created_on","operator":"this_month"}]}'
+```
+
+**See [references/list-query-examples.md](references/list-query-examples.md) for more filter, sort, pagination, and combined query examples.**
+
+### Record Mutations
+
+Create:
+
+```bash
+docyrus ds create crm contacts --data '{"name":"Jane Doe","email":"jane@example.com"}'
+```
+
+Update:
+
+```bash
+docyrus ds update crm contacts <recordId> --data '{"phone":"+1234567890"}'
+```
+
+Delete:
+
+```bash
+docyrus ds delete crm contacts <recordId>
+```
+
+Batch and file input:
+
+```bash
+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`.
+
+```bash
+# 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
+
+```bash
+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:
+
+```bash
+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](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 combined queries.