Corvio Workspace CLI

Official CLI for a user's Corvio Workspace. It supports an existing CORVIO_API_KEY and a browser device-link login. In a connected host, use the accompanying corvio-operate-workspace Skill so every non-trivial task begins with a lightweight Corvio grounding check.

npm install --global @corvio/cli@beta
export CORVIO_API_KEY='cvu_...'
corvio auth status
corvio agents connect --provider codex --project . --json
corvio collaboration status --json --no-input
corvio ask --prompt 'Summarize recurring launch risks' --json
corvio ask --background --prompt 'Reconcile the current launch evidence' --json
corvio questions operation <operation_id> --after-cursor <progress_cursor> --wait-until-terminal --json
corvio questions cancel <operation_id> --yes --json
corvio files upload --file ./research.pdf --json
corvio files get <asset_id> --content --json
corvio files organize <asset_id> --instruction 'Create a reusable decision brief' --yes --wait-until-terminal --timeout-seconds 1200 --json
corvio files operation <operation_id> --wait-until-terminal --timeout-seconds 1200 --json
corvio files resume <operation_id> --yes --wait-until-terminal --timeout-seconds 1200 --json
corvio docs read <workspace_id/document_id> --mode auto --json
corvio docs patch <workspace_id/document_id> --input ./patch.json --operation-id <id> --yes --json
corvio docs table-read <workspace_id/document_id> --limit 25 --json
corvio docs table-mutate <workspace_id/document_id> --input ./table-change.json --change-summary 'Updated owner and due date' --yes --json
corvio sync init --dir ./knowledge --root-node-id <node_id> --json
corvio update check --json

When no environment key is configured, run corvio auth login. Login creates one user-level cvu_ control-plane credential; it does not freeze the browser's current Workspace. Run corvio agents connect --project . from the project you want to expose. The command verifies the selected Codex, Claude Code, or Copilot host before server mutation, then idempotently creates or restores the Agent for that provider/device/project binding, grants current/future Workspace coverage under live membership/role and ACL limits, saves the one-time cvg_ in a 0600 multi-binding registry, and installs that project's listener under the current user's systemd or launchd service manager. auto falls back to a detached listener only when neither manager is available; --listener-mode managed instead fails closed, and --listener-mode detached is an explicit session-scoped compatibility choice. corvio collaboration status then checks local foreground prerequisites and reports package freshness, contract compatibility, installation ownership, exact listener supervision, every discoverable Skill copy, and the fact that host loading is not observable. A local comment listener receives inbound @Agent work; it does not make an unrelated foreground coding session collaborate automatically. Another project gets another Agent. Ordinary data commands prefer the binding whose root contains the current directory, then a locally confirmed selection, the account selection, the personal default, or one authorized candidate. They ask only on real ambiguity. Use corvio workspaces use, --workspace, and --agent as explicit routing/reproducibility controls. Legacy Workspace-bound cvk_, cvg_, and version-1 credential files remain compatible and are never widened. Local sync stores only credential-free handles and revision/hash baselines in .corvio/state.json; Markdown lives below corvio_docs/, and conflicts require explicit resolution. corvio capabilities reads only Corvio API capability and compatibility facts, so discovery remains usable in hosts that deny npm registry access. corvio update check is the explicit registry-backed version check; it never self-installs. See the Corvio CLI guide for the full command and receipt contract.

CLI and Skill updates are independent. corvio update check checks the CLI package only. corvio collaboration status detects a missing, incompatible, compatible-but-not-current, or conflicting local Skill, but never mutates host directories. Non-current receipts include one compact Agent notice and a source-aware action; current copies stay quiet. For standalone Skill refreshes, the command pins the verified installer, selects exactly one provider, preserves project/global scope, and returns a verification command. Use corvio collaboration status --provider workbuddy --json --no-input to inspect WorkBuddy's manual copy at ~/.workbuddy/skills/corvio-operate-workspace/; this does not prove which bytes a running WorkBuddy conversation loaded. The canonical website ZIP is a static local copy and is not update-tracked by npx skills update; reinstall from the same source and scope, then start a fresh host session. Until a reviewed WorkBuddy marketplace listing is live, a WorkBuddy upload is an unmanaged manual install and cannot auto-update from Corvio. Remote MCP changes are server-delivered and normally need only a refreshed host session unless new OAuth scopes require reauthorization.

The CLI rejects unknown/duplicate options and malformed integer bounds before network access. Normal API calls have a bounded timeout (CORVIO_REQUEST_TIMEOUT_MS, maximum ten minutes); only reads, explicit idempotency contracts, revision guards, and other owner-declared safe operations retry automatically. Document commands accept both bare document IDs and canonical workspace_id/document_id handles; a canonical handle that disagrees with the selected Workspace fails before remote access, and successful reads return canonical_id for direct reuse. docs read --mode auto returns a complete small Page or a large-Page overview, then supports exact section, line-range, literal-search, and full projections. docs patch applies 1–20 exact non-overlapping L# replacements at the fetched revision and returns a compact readback instead of replaying untouched content. docs get --output keeps compatibility full-body download but omits the body from stdout; create/update request compact mutation receipts. Document updates preflight only a bounded overview for the current revision when --expected-revision is omitted. docs table-read returns a bounded stable-ID projection; docs table-mutate accepts a JSON payload for at most 50 cell updates or row appends and requires the fetched revision, while formulas, styles, structure, sorting, and semantic transformations remain corvio ask --allow-actions work. When the executing principal is a connected Agent, document and table mutations also require --change-summary, create a visible document-level comment after the guarded update, and return its receipt; a comment failure is reported as a partial effect rather than silent success. When a Corvio document or comment supplied the task, use corvio agent closeout to return the verified outcome, optionally resolve the thread, and read both document and thread back. Downloads, uploads, and Markdown pulls verify SHA-256 receipts before replacing local files; local writes are atomic, remote default filenames cannot escape the current directory, and Sync refuses symbolic-link traversal while checkpointing each successful push.

For corvio ask, keep the user's natural question unchanged, then append the smallest complete decision-relevant context or stable handles as a separate clause. A carried Project handle normally bounds a cross-branch question without enumerating all descendants. Handles are evidence addresses: do not invent a comparison rubric, prescribe reasoning steps, substitute another user objective, or turn current Tree labels into a detailed task plan. Unless the user chose them, do not invent taxonomy, titles, artifact counts, or Corvio's internal plan. In a bounded read-only continuation, use corvio ask --workspace <workspace_id> --prompt "<unchanged question; Context: project handle>" --json --no-input when a trusted current-task or prior receipt already proves this authenticated CLI and exact Workspace. Answer-only is the default: omit --allow-actions; the CLI has no --mode option. Start the command once; do not launch an identical Question concurrently or retry before terminal exit. The command returns the terminal Question without model-visible polling. Transport continuity does not prove a cheaper processing profile; leave profile selection on auto unless the unresolved semantic bottleneck independently justifies another profile. Do not install, probe, or switch to the CLI only for that optimization, and do not extend it to an unbound Workspace. Read the terminal Question receipt and use artifact.url or links.primary_artifact verbatim; reader_output artifacts are deliverables, structure_container artifacts are hierarchy, and node_id is never a document URL.

For a Question that may outlive one host turn, add --background. The command returns one durable operation_id immediately. Continue that same operation with corvio questions operation; --wait-until-terminal keeps the status loop inside the CLI, while --after-cursor returns only later user-visible milestones. A local deadline is not remote cancellation. Use corvio questions cancel <operation_id> --yes to request a stop, and do not report success until the returned state is actually cancelled. Progress is a bounded phase summary, never hidden reasoning or a provisional final answer. To correct the objective, finish or cancel the current operation and start a successor corvio ask --conversation-id <conversation_id> rather than silently replacing it.

Treat files as a value ladder, not one upload event. Upload/finalize preserves the exact original, provenance, hash, policy, and stable Asset ID. A selected Markdown file can become an editable Page through corvio docs create --file; for other formats or a coherent source set, use corvio files organize or corvio ask --allow-actions to produce the reader-facing Page, Spreadsheet, Presentation, Code, HTML Artifact, or reading layer that fits the task. Stable facts/preferences may enter Memory; only an evidence-backed reusable method, configuration, constraint, or quality bar should become a Project Skill.

Use corvio files get <asset_id> --content when the task needs only bounded facts from one retained source. The response preserves the immutable original as authority, reports its source hash and whether the projection is complete or truncated, and does not create a Question or materialize another document. Never infer unseen workbook rows/sheets or document sections.

File organization is asynchronous. A queued organization receipt is progress, not completion. When this authenticated CLI is already the natural transport, --wait-until-terminal keeps deterministic status reads inside one foreground process; --timeout-seconds is a bounded local deadline, and expiry returns the latest non-terminal receipt with transport_wait.status=deadline_reached. Without that flag, corvio files operation <operation_id> remains one immediate read. Blocked operations expose their typed error and can be continued with corvio files resume <operation_id> --yes; queued/running/blocked operations can be stopped with corvio files cancel <operation_id> --yes. Report completion only after the terminal receipt exposes the output document, source reconciliation, Skill evaluation, and durable links. skills_extraction_mode=always requires the evaluation; evaluated_no_qualifying_skill is a valid terminal result and is preferable to a fabricated Skill.

Project Agent collaboration

Connect the current project with the user credential. User and Agent credentials stay deliberately separate, and the secret is never printed, written into the project, or passed to the provider:

corvio agents connect --provider codex --project . --json

Without --display-name, connect derives a provider-aware project name from the authenticated user, such as Ada Codex · billing-service; Settings remains the rename owner. The receipt distinguishes Configured, CLI Ready, Listening, Offline, and Foreground collaboration ready, and includes the stable Agent, opaque project binding, Workspace scope, host permission/trigger policy, Skill status, and Settings link. The default workspace_write profile uses the provider's native sandbox. owner_only is the safe trigger default. Allowing Workspace members to invoke the local project or granting unrestricted host access requires explicit --yes.

The listener first runs a read-only provider planning pass, then asks Corvio Query for exact origin-document and collaboration context. local_project work runs inside the bound project; online document writes remain Query/Writer-owned. The provider consumes the Query result before replying, and completion records exact event/lease/question/comment lineage plus provider, project fingerprint, claimed files/checks, and observed Git working-tree state. A custom handler remains available for advanced adapters:

The Codex adapter requires an existing saved codex login session. It selects Codex's built-in authenticated provider and applies a secret-filtered core shell environment to model-run project commands; it does not forward environment-only custom-provider keys as an unattended fallback. Claude Code and Copilot use their own saved authentication and native permission modes. Provider capability summaries are observable facts, not a claim that all three hosts enforce identical sandboxes.

{"instruction":"Inspect the mentioned section and correct unsupported claims.","reply":"Reviewed and updated the section."}

The Runner renews the mailbox lease, binds Query to the exact event and source document, posts the only visible reply under the explicitly mentioned Agent's own name/provider avatar, and completes only with durable Query/comment/runtime receipts. Inbound comment runs cannot search another Workspace through the owner's account Agent. Neither CORVIO_API_KEY nor CORVIO_AGENT_API_KEY is passed to the provider/handler, and runtime commands never fall back across Agent principals. The project path stays only in the local registry; Corvio stores its opaque fingerprint and capability summary.

Runner replies are causally bound to the claimed event and are idempotent across network retries. Corvio stops repeated Agent routes and enforces bounded hop, chain-event, and per-comment target budgets; a stopped handoff remains visible as “Needs attention” but is not claimable. For a deliberate standalone Agent-to-Agent request, use corvio agent comment ... --start-new-chain. Manual replies may instead pass --source-event-id with --source-event-lease-token; source and new-chain modes must not be mixed.

If a laptop sleeps, loses network, or stops the Runner, events remain pending or become reclaimable after lease expiry. Corvio does not claim to power on an offline device. On Linux and macOS, the default user service restarts a crashed listener and starts it again when that user's service manager returns; Linux also applies bounded restart and memory policy to the listener/provider subtree. It does not bypass login, sleep, shutdown, provider authentication, or an administrator-disabled user service. Re-run agents connect --listener-mode managed to reconcile the same service, or pause/revoke the Agent in Settings when it should stop receiving new mentions. --no-listen is an explicit diagnostic override and returns an honest Offline receipt.

Publish already-authored source bundles

corvio files publish --manifest ./corvio-publication.json --operation-key <stable-operation> --wait-until-terminal --timeout-seconds 600 --json --no-input packages selected relative files, retains one private ZIP, and publishes declared Pages/images through canonical Workspace transactions. The manifest fixes namespace, source keys, regions, hierarchy and carrier; no model retypes source bytes.

Use files publication-contract for the exact schema, files bundle --manifest <path> --output <zip> to package offline, or files publish --source-asset-id <workspace_uuid/asset_uuid> --operation-key <key> for a retained bundle. Read files publication <workspace_uuid/operation_uuid> --detail full for the complete ledger. An interrupted operation resumes with the same key; different source bytes require a new operation. Human edits return region conflicts, and merges require the current Block hashes. Static HTML uses the existing immutable HTML Artifact builder and rejects executable source. New Pages/images default to private.

Compact receipts include caller-declared entry Pages in source order. Use files publication <handle> --page-keys <key,key> --image-keys <key,key> for selected evidence, or --detail full for the entire inventory. Confirmed counts and the source hash prove the closed publication at its recorded revisions; current human edits require current Page reads.