xeroctl platform operations

Overview

Every subcommand resolves the active deployment via config use and issues bearer-authenticated requests against the InferenceRouter. No browser required.

All platform commands read the active deployment for base URL and API key (the project id is derived from base_url). Override any single invocation with --context, --base-url, or --api-key.

Command	Verbs	Router path	Required scope
`maintenance`	6	`/v1/management/maintenance/*`	`management`
`project`	8	`/v1/management/project/*` (delegation create/revoke is handled via `approvals`)	`management`
`settings`	3	`/v1/settings/*`	`management`
`usage`	4	`/v1/usage/*`	`inference`
`exports`	5	`/v1/exports/*`	`management`
`health`	2	`/v1/health/dashboard`	`management`
`workspaces`	9	`/v1/workspaces/*`	`inference`
`chats`	10	`/v1/chats/*`	`inference`

Scope mismatch: calling a management-scoped route with an API key that only carries inference scope returns a 403 with error.code = scope_insufficient. Issue a management-scope key via xeroctl keys create --scope management before running these commands.

maintenance

// 6 verbs list schedule update cancel complete purge

Schedule, update, cancel, complete, and purge maintenance windows for the active project. Severity values: info, warning, critical.

Subcommands

bash

                    xeroctl maintenance list                        # List all windows
xeroctl maintenance list --status scheduled     # Filter by status
xeroctl maintenance schedule \                  # Schedule a new window
  --title "Patching worker-7" \
  --description "Routine kernel update" \
  --starts-at 2026-05-01T02:00:00Z \
  --ends-at 2026-05-01T04:00:00Z \
  --severity warning
xeroctl maintenance update <id> --ends-at ...   # Patch a window
xeroctl maintenance cancel <id>                  # Cancel a scheduled window
xeroctl maintenance complete <id>                # Mark a window complete
xeroctl maintenance purge <id>                   # Hard-delete a cancelled window
                

When to use each

cancel, window has not started yet and needs to be called off.
complete, window finished naturally; closes the notification period.
purge, window was cancelled and you want it out of the list. Requires window status to be cancelled.

project

// 8 verbs across 3 groups members: list add update remove · invitations: list resend revoke · delegations: list

Manage project team members, invitations, and role delegations.

members

bash

                    xeroctl project members list                          # List members
xeroctl project members add --email user@example.com \ # Invite a member
  --role member
xeroctl project members update <id> --role owner      # Change role
xeroctl project members remove <id>                    # Remove a member
                

invitations

bash

                    xeroctl project invitations list                   # List open invitations
xeroctl project invitations resend <id>             # Resend the email
xeroctl project invitations revoke <id>             # Revoke an unaccepted invitation
                

delegations

bash

xeroctl project delegations list # List role delegations

Delegation grants (creating / revoking destructive-approval delegations) are managed through the approvals command group.

settings

// 3 verbs get update delete

Read, update, or delete project-level settings. Excludes 2FA (stays browser-only by design).

bash

                    xeroctl settings get                                   # Show the active project's settings
xeroctl settings update \                              # Patch one or more fields
  --name "Platform Ops" \
  --description "Owns router + agent infrastructure"
xeroctl settings delete --confirm "Platform Ops"       # Soft-delete (typed confirmation)
                

Typed confirmation: --confirm takes the project's authoritative name as its value. The server re-reads the name and rejects mismatched values with 400 confirmation_mismatch. Deletion is soft; restore is performed from the browser settings panel.

usage

// 4 verbs events logs endpoints uptime

Query usage events, request logs, per-endpoint rollups, and uptime snapshots.

bash

                    xeroctl usage events                                            # Latest usage events
xeroctl usage events --since 2026-04-01T00:00:00Z --until 2026-04-30T23:59:59Z
xeroctl usage logs                                              # Request-level logs
xeroctl usage logs --q /v1/chat/completions --limit 100
xeroctl usage endpoints                                         # Per-endpoint rollups
xeroctl usage uptime                                            # Uptime / SLO summary
                

Common options

Option	Description	Subcommands
`--since <ts>`	ISO 8601 lower bound	`events`, `logs`, `endpoints`
`--until <ts>`	ISO 8601 upper bound	`events`, `logs`, `endpoints`
`--limit <n>`	Max rows returned (router clamps to 500)	`events`, `logs`
`--q <substring>`	Case-sensitive substring match on the request path	`logs`

exports

// 5 verbs create status download cancel + types logs metrics usage executions

Create, monitor, download, and cancel data exports.

bash

                    xeroctl exports create --type logs \
  --since 2026-04-01T00:00:00Z --until 2026-04-30T23:59:59Z
xeroctl exports create --type metrics \
  --since 2026-04-24T00:00:00Z --until 2026-04-30T23:59:59Z --format jsonl
xeroctl exports create --type usage \
  --since 2026-04-01T00:00:00Z --until 2026-04-30T23:59:59Z
xeroctl exports status <id>                                # Check export status
xeroctl exports download <id> --output-file out.ndjson    # Download completed export
xeroctl exports cancel <id>                                # Cancel a queued or running export
                

Both bounds required: --since and --until are validated client-side; the router rejects bodies missing either bound. Recognised --type values are logs, metrics, usage, and executions. Valid --format values are json (default), csv, and jsonl.

Execution exports: xeroctl exports create --type executions returns 202 Accepted with the export job id; poll xeroctl exports status <id> until status=completed and then download the NDJSON bundle with xeroctl exports download <id> --output-file <path>.ndjson. The router serves application/x-ndjson.

health

// 2 verbs dashboard services

Summary views onto router and agent health for the active project.

bash

                    xeroctl health dashboard                        # Overall project health
xeroctl health services                         # Per-service breakdown
                

Both subcommands call the per-project GET /v1/health/dashboard route and render a project-filtered summary; services reformats the same payload into a per-service breakdown. Platform-wide status belongs on the public /status page and is not exposed here.

workspaces

// 9 verbs across 3 groups crud+search: list create show update delete search · memories: list create delete · files: list

Full workspace CRUD, semantic search, memory management, and file listing.

CRUD + search

bash

                    xeroctl workspaces list                          # List workspaces
xeroctl workspaces create --name "ops" \         # Create a workspace
  --description "Operational scratchpad"
xeroctl workspaces show <id>                     # Detailed view
xeroctl workspaces update <id> --name "ops-v2"   # Rename
xeroctl workspaces delete <id>                    # Delete a workspace
xeroctl workspaces search <id> \                  # Semantic search
  --query "kernel panic on worker-7" \
  --k 20                                          # Top-K result count
                

memories

bash

                    xeroctl workspaces memories list <id>                                          # List memories
xeroctl workspaces memories create <id> --content "..." \                       # Add a memory
  [--source-type user|chat|tool] [--category <str>] \
  [--source-chat-id <cid>] [--source-message-id <mid>]
xeroctl workspaces memories delete <id> <memory-id>                             # Delete a memory
                

files

bash

                    xeroctl workspaces files list <id>                        # List workspace files
                

Use xeroctl uploads for file uploads and the workspace revalidation commands. The workspaces files list command shown here provides a read-only inventory.

chats

// 10 verbs across 5 groups crud: list create show update delete · branches: list fork · messages: list · memories: list · context: (positional)

Chat ecosystem commands covering CRUD, branches, messages, memories, and per-chat context retrieval.

CRUD

bash

                    xeroctl chats list                               # List chats (scoped by the active API key)
xeroctl chats list --limit 50                    # Cap row count
xeroctl chats create --title "Triage" \          # Create a chat
  [--system-prompt "..."] [--model-id <mid>] [--visibility private|shared]
xeroctl chats show <id>                          # Detailed view
xeroctl chats update <id> --title "New title"
xeroctl chats delete <id>                        # Delete a chat
                

branches

bash

                    xeroctl chats branches list <id>                 # List branches
xeroctl chats branches fork <id> \                # Fork a branch
  --from-message <msg-id> --name "hypothesis-b"
                

messages

bash

                    xeroctl chats messages list <id>                 # List messages on the default branch
xeroctl chats messages list <id> --branch <bid> --limit 50
                

memories

bash

xeroctl chats memories list <id> # List chat memories

context

bash

xeroctl chats context <id>

context takes only the positional chat id and returns the semantic-search bundle used by pre-dispatch retrieval. On deployments where workspace retrieval is not enabled, the command returns an empty bundle ({"items": [], "reranker_latency_ms": 0}) so scripted callers can handle both configurations uniformly.

Examples

Schedule an outage window

bash

                    xeroctl maintenance schedule \
  --title "Router restart for config rollout" \
  --description "Rolling restart across us-east" \
  --starts-at 2026-05-02T06:00:00Z \
  --ends-at 2026-05-02T06:30:00Z \
  --severity info \
  --affected-services router,frontend
                

Onboard a new team member

bash

                    xeroctl project members add --email new-hire@example.com --role member
xeroctl project invitations list                  # Confirm the invite is pending
# ... they accept the email ...
xeroctl project members list                      # Confirm they appear
                

Audit usage for the last 30 days

bash

                    SINCE=2026-04-20T00:00:00Z
UNTIL=2026-05-20T00:00:00Z

xeroctl usage endpoints --since "$SINCE" --until "$UNTIL"
xeroctl usage uptime
xeroctl exports create --type usage --since "$SINCE" --until "$UNTIL"
                

Set up a workspace + triage chat

bash

                    WS_ID=$(xeroctl workspaces create --name "incident-2026-04-14" -o json | jq -r .id)
CHAT_ID=$(xeroctl chats create --title "Triage" -o json | jq -r .id)

xeroctl chats context "$CHAT_ID"
xeroctl workspaces search "$WS_ID" --query "known degradation patterns" --k 20
                

xeroctl platform ops

Overview

maintenance

Subcommands

When to use each

project

members

invitations

delegations

settings

usage

Common options

exports

health

workspaces

CRUD + search

memories

files

chats

CRUD

branches

messages

memories

context

Examples

Schedule an outage window

Onboard a new team member

Audit usage for the last 30 days

Set up a workspace + triage chat

xeroctl CLI

xeroctl config

xeroctl exec

xeroctl approvals