# @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/`.
Knowledge-graph caches and vector indexes are stored under `<settings-root>/knowledge/<workspace-hash>/`.
Tracked repo knowledge lives in `docyrus/knowledge/`.
`docyrus tui` requires [Bun](https://bun.sh) installed locally.

## Installation

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

or

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

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

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

## Help

```bash
docyrus
docyrus --help
docyrus env --help
docyrus auth --help
docyrus discover --help
docyrus knowledge --help
docyrus project-plan --help
docyrus ds --help
docyrus apps --help
docyrus studio --help
docyrus connect --help
docyrus agent --help
docyrus coder --help
docyrus server --help
docyrus tui --help
```

## Knowledge Graph

Initialize and use the repo knowledge graph:

```bash
docyrus knowledge init
docyrus knowledge generate-initial
docyrus knowledge refresh
docyrus knowledge locate "Working Agreement" --json
docyrus knowledge section "knowledge#Working Agreement" --json
docyrus knowledge refs "knowledge#Working Agreement" --json
docyrus knowledge search "how should agents use this repo?" --json
docyrus knowledge expand "Read [[Working Agreement]] before editing" --json
docyrus knowledge check --json
docyrus knowledge config --json
```

## Project Plan

The project plan is a repo-tracked work graph stored at `docyrus/project-plan/project-plan.json`. It organizes work into sections (standalone groupings like phases or feature areas), features, and tasks. A derived `PROJECT_PLAN.md` is always kept in sync. Features are also synced into the knowledge base features document when it exists.

Manage sections, features, and tasks:

```bash
docyrus project-plan show --json
docyrus project-plan check --json
docyrus project-plan ensure --json

# Sections
docyrus project-plan upsert-section --title "Core Features" --json
docyrus project-plan upsert-section --title "Testing" --slug "testing" --summary "Test coverage" --json

# Features
docyrus project-plan upsert-feature --sectionId "<section-id>" --title "Auth Flow" --json
docyrus project-plan upsert-feature --sectionId "<section-id>" --title "Data Export" --slug "data-export" --summary "CSV and JSON export" --json

# Tasks
docyrus project-plan upsert-task --featureId "<feature-id>" --title "Implement OAuth2" --type new-implementation --assignee agent --json
docyrus project-plan upsert-task --featureId "<feature-id>" --title "Fix token refresh" --type bug-fix --assignee agent --status in_progress --json
docyrus project-plan get-task --taskId "<task-id>" --json
docyrus project-plan set-task-status --taskId "<task-id>" --status done --json

# Linked local subtasks
docyrus project-plan create-linked-todo --taskId "<task-id>" --json
docyrus project-plan create-linked-todo --taskId "<task-id>" --title "Step 1" --body "Details" --json
```

Task types: `new-implementation`, `bug-fix`, `api-test`, `browser-automation-test`, `work`
Assignees: `agent`, `user`
Statuses: `planned`, `in_progress`, `blocked`, `done`

## Data Sources

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

## OpenAPI Discovery

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

## Connectors

```bash
docyrus connect list-connectors --json
docyrus connect get-connector <slug> --json
docyrus connect get-action <slug> <actionKey> --json
docyrus connect list-connections <slug> --json
docyrus connect curl <slug> <endpoint> --json
docyrus connect run-action <appSlug> <actionKey> --json
```

## Apps and Studio

List and manage apps:

```bash
docyrus apps list --json
docyrus apps delete --appId "<app-id>" --json
docyrus apps restore --appId "<app-id>" --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
```

## Raw API Access

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

## TUI

Launch the OpenTUI terminal UI (requires Bun):

```bash
docyrus tui
```

## Agent Server

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

## Pi Agent and Coding Agent

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

### Built-in Agent Tools

When `docyrus/knowledge/` exists, `docyrus agent`, `docyrus coder`, and `docyrus server` load built-in knowledge tools:

- `docyrus_knowledge_search`
- `docyrus_knowledge_section`
- `docyrus_knowledge_locate`
- `docyrus_knowledge_refs`
- `docyrus_knowledge_expand`
- `docyrus_knowledge_check`

When `docyrus/project-plan/project-plan.json` exists, the `project_task` tool is also loaded with actions: `show`, `get`, `create-section`, `create-feature`, `create-task`, `set-status`, `create-linked-todo`.

The `todo` tool is always available with actions: `list`, `list-all`, `get`, `create`, `update`, `append`, `delete`, `claim`, `release`.

### Slash Commands

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
/architect [brief] # discover tenant data sources and generate planning artifacts under ./docyrus/architecture/
/end-architect    # alias for leaving an architect planning session
/plan-policy      # show the effective planning-model policy and the resolved planning model
/read-only        # enter read-only mode — write and edit tools are disabled
/end-read-only    # exit read-only mode and resume normal operation
/tasks            # browse the canonical project-plan sections, features, and tasks
/todos            # interactive todo manager
```

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

### Planning-Model Policy

Optional planning-model policy for controlling which model is used during `/plan` sessions:

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