# @docyrus/docyrus

Docyrus API CLI.

CLI state files are stored under the active `.docyrus/` scope.

- Local default: `./.docyrus/`
- Global override: `~/.docyrus/` via `-g` / `--global`

Tenant OpenAPI files are stored under `<settings-root>/tenans/<tenantId>/openapi.json`.
Pi agent state for `docyrus agent` and `docyrus coder` is stored under `<settings-root>/pi/agent/`.
`docyrus tui` requires [Bun](https://bun.sh) installed locally.

## Installation

```bash
npm install -g @docyrus/docyrus
```

or

```bash
pnpm add -g @docyrus/docyrus
```

## Environments

List and switch environments:

```bash
docyrus env list
docyrus env use live
```

Default environments:
- `live` -> `https://api.docyrus.com`
- `beta` -> `https://beta-api.docyrus.com`
- `alpha` -> `https://alpha-api.docyrus.com`
- `dev` -> `https://localhost:3366`

Aliases:
- `prod` -> `live`

## Authentication

Login with explicit client ID:

```bash
docyrus auth login --clientId "<your-client-id>"
```

After a successful login, the client ID is saved in `~/.docyrus/config.json` and reused by default.

Logout active account:

```bash
docyrus auth logout
```

## Help

```bash
docyrus
docyrus --help
docyrus env --help
docyrus auth --help
docyrus discover --help
docyrus ds --help
docyrus apps --help
docyrus studio --help
docyrus agent --help
docyrus coder --help
docyrus tui --help
```

## Example Usages

Get current environment and active user/tenant context:

```bash
docyrus --json
```

Switch environment:

```bash
docyrus env use beta
docyrus env list --json
```

Login and inspect current identity:

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

List apps:

```bash
docyrus apps list --json
```

Download current tenant OpenAPI spec:

```bash
docyrus discover api --json
```

Discover from downloaded tenant OpenAPI spec:

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

Work with accounts and tenants:

```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 "<tenant-id-uuid-or-tenant-no>" --userId "<user-id>" --json
```

Query data source items:

```bash
docyrus ds list base task --columns "id,name,status" --limit 10 --orderBy "created_on desc" --json
```

Create, update, delete data source items:

```bash
docyrus ds create base task --data '{"name":"My Task","status":"open"}' --json
docyrus ds update base task "<record-id>" --data '{"status":"done"}' --json
docyrus ds delete base task "<record-id>" --json
```

Add comments and file attachments to a record:

```bash
docyrus ds comments create base task "<record-id>" --message "Looks good" --json
docyrus ds files upload base task "<record-id>" --file ./contract.pdf --json
```

Batch create/update (max 50 items) and file input (`--from-file` supports `.json` and `.csv`):

```bash
docyrus ds create base task --data '[{"name":"Task 1"},{"name":"Task 2"}]' --json
docyrus ds update base task --data '[{"id":"1","status":"done"},{"id":"2","status":"open"}]' --json
docyrus ds create base task --from-file ./tasks.csv --json
docyrus ds update base task --from-file ./tasks-update.json --json
```

Call raw API endpoints via curl command:

```bash
docyrus curl /users/me -i --json
docyrus curl /dev/apps --json
```

Manage dev studio data sources, fields, and enums:

```bash
docyrus studio list-data-sources --appSlug base --expand fields --json
docyrus studio get-data-source --appSlug base --dataSourceSlug task --json
docyrus studio create-data-source --appSlug base --title "Tasks" --name "task" --slug "task" --json
docyrus studio update-data-source --appId "<app-id>" --dataSourceId "<data-source-id>" --data '{"title":"Tasks v2"}' --json
docyrus studio delete-data-source --appId "<app-id>" --dataSourceSlug "task" --json
docyrus studio bulk-create-data-sources --appId "<app-id>" --from-file ./data-sources.json --json
docyrus studio list-fields --appSlug base --dataSourceSlug task --json
docyrus studio get-field --appSlug base --dataSourceSlug task --fieldSlug status --json
docyrus studio create-field --appId "<app-id>" --dataSourceId "<data-source-id>" --name "Status" --slug "status" --type "text" --json
docyrus studio update-field --appId "<app-id>" --dataSourceId "<data-source-id>" --fieldId "<field-id>" --data '{"name":"Stage"}' --json
docyrus studio delete-field --appId "<app-id>" --dataSourceId "<data-source-id>" --fieldSlug "status" --json
docyrus studio create-fields-batch --appId "<app-id>" --dataSourceId "<data-source-id>" --data '[{"name":"Priority","slug":"priority","type":"text"}]' --json
docyrus studio update-fields-batch --appId "<app-id>" --dataSourceId "<data-source-id>" --from-file ./fields-update.json --json
docyrus studio delete-fields-batch --appId "<app-id>" --dataSourceId "<data-source-id>" --data '["field-1","field-2"]' --json
docyrus studio list-enums --appId "<app-id>" --dataSourceId "<data-source-id>" --fieldId "<field-id>" --json
docyrus studio create-enums --appId "<app-id>" --dataSourceId "<data-source-id>" --fieldId "<field-id>" --data '[{"name":"Open","sortOrder":1}]' --json
docyrus studio update-enums --appId "<app-id>" --dataSourceId "<data-source-id>" --fieldId "<field-id>" --from-file ./enums-update.json --json
docyrus studio delete-enums --appId "<app-id>" --dataSourceId "<data-source-id>" --fieldId "<field-id>" --data '["enum-1","enum-2"]' --json
```

Launch the OpenTUI terminal UI (requires Bun):

```bash
docyrus tui
```

Start the agent HTTP server:

```bash
docyrus server
docyrus server --port 4000
docyrus server --profile agent
docyrus server --model anthropic/claude-sonnet-4-20250514 --thinking high
```

For full endpoint documentation see [docs/API.md](docs/API.md).

Launch the scoped pi assistant and coding agent:

```bash
# Interactive TUI
# First interactive launch opens the DOCYRUS onboarding wizard if no provider is configured yet.
docyrus agent
docyrus coder

# Interactive TUI with an initial prompt
docyrus agent "Inspect the active tenant and list apps"
docyrus coder "Add a command to list my team dashboards"

# One-shot mode
docyrus agent --print "Which tenant am I using?"
docyrus coder --print --mode json "Summarize the CLI command surface in this repo"
```

Inside the interactive agent TUI:

```bash
/login   # browser or API-key provider chooser
/logout  # remove saved provider configuration
/plan [task]  # start a planning-only branch and keep the current plan in .docyrus/plans/
/end-plan  # leave the planning branch, summarize it, and return to the original branch
/end-architect  # alias for leaving an architect planning session
/plan-policy  # show the effective planning-model policy and the resolved planning model
/architect [brief]  # discover tenant data sources and generate local planning artifacts under ./docyrus/architecture/
```

When running through `docyrus server`, `/plan` and `/architect` can be sent through `/api/chat` as normal chat input. If clarification is needed, the server emits a synthetic `ask_user` client tool. Frontends using AI SDK `useChat` should render that tool and submit structured answers back with `addToolOutput`.

Optional planning-model policy:

- Project config: `<project>/.pi/plan-policy.json`
- Global config: `~/.pi/agent/plan-policy.json`
- Project config takes precedence over global config

Example:

```json
{
  "models": [
    { "model": "anthropic/claude-sonnet-4", "thinkingLevel": "high" },
    "openai-codex/gpt-5.3-codex"
  ],
  "profiles": {
    "codex-implementation": {
      "match": "openai-codex/gpt-5.3-codex",
      "models": [
        { "model": "anthropic/claude-sonnet-4", "thinkingLevel": "medium" }
      ]
    }
  }
}
```

`match` is the exact implementation-time `provider/modelId` active when `/plan` starts. The `models` array is an ordered fallback chain. If no configured planning model resolves, `/plan` stays on the current session model.
