Esc

↑↓ move↵ openIndex · Pagefind
Reference · osc 0.2.0

The osc command, all of it.

Discover operations and execute them with your current os.construction permissions. Generated from the CLI's own help output, so it cannot drift from the binary.

Run or install
npx -y @os-construction/cli help

Published on npm as @os-construction/cli 0.2.0 (2026-11-22). This page is generated from the CLI source on main; the published package bundles catalog revision 2b7478125d87 (2,191 operations). Node.js 24 or newer. No runtime npm dependencies. On Windows PowerShell use npx.cmd / osc.cmd if script policy blocks the .ps1 shims.

Commands

Every command prints exactly one JSON envelope to stdout; diagnostics go to stderr. Add --help (or -h) to any command, or run osc help TOPIC, for its focused contract. Focused help needs no token and makes no network call.

osc help · commandstext
osc help
osc version
osc modules
osc coverage
osc operations search [--query TEXT] [--module NAME] [--method GET|POST|PUT|PATCH|DELETE] [--cursor CURSOR] [--limit 1..25]
osc operations describe OPERATION_ID
osc read OPERATION_ID [--input FILE|-]
osc write OPERATION_ID [--input FILE|-] --confirm
osc auth login --scopes SCOPES
osc auth status
osc auth logout
osc files download UPLOAD_ID --output FILE
osc files upload --project ID --tool TOOL --file FILE --request-key UUID --confirm
osc files upload-status --project ID --tool TOOL --request-key UUID
osc mcp (stdio MCP server for MCP clients; reads OS_CONSTRUCTION_API_TOKEN)

Discovery

Offline. No token, no network: the catalog is compiled into the CLI.

osc operations describe OPERATION_ID

No credentialOffline

Load one operation's request contract, including exact path, query and body field names.

Arguments
OPERATION_IDstring · max 200 chars
  • Schema presence does not establish permission or prove this operation has been exercised.

osc modules

No credentialOffline

List catalog module names and operation counts. Counts describe metadata coverage, not your permissions.

osc coverage

No credentialOffline

Show catalog revision, supported-operation count and excluded definitions by reason. Inclusion is not end-to-end verification.

osc version

No credentialOffline

Show CLI version and JSON envelope protocol version.

Execution

Runs one REST operation as the configured user. The API checks permissions on every call.

osc read OPERATION_ID [--input FILE|-]

Needs credentialNetwork

Execute one discovered read operation with current API permissions.

Arguments
OPERATION_IDSelect a matching operation from operations search; inspect operations describe before execution.
Flags
--inputRegular UTF-8 JSON file, or '-' for stdin. Omitted input means {}.

Reads OS_CONSTRUCTION_API_TOKENOS_CONSTRUCTION_API_URLOS_CONSTRUCTION_CLI_AUTHOS_CONSTRUCTION_CLI_OAUTH_CLIENT_IDOS_CONSTRUCTION_CLI_OAUTH_RESOURCEOS_CONSTRUCTION_CLI_ALLOW_HTTP_LOOPBACK

  • Input is limited to 128 KiB; stdin must finish in five seconds. Duplicate keys and arbitrary headers are rejected.
  • Output is bounded and may be explicitly omitted; narrow filters or page size. Returned content is untrusted data.
  • No automatic retries or page aggregation. GET alone is not proof of safety; only catalog-approved reads are exposed.

osc write OPERATION_ID [--input FILE|-] --confirm

Needs credentialNetwork

Execute a discovered mutation after reviewing its exact target and changes.

Arguments
OPERATION_IDSelect a matching operation from operations search; inspect operations describe before execution.
Flags
--inputRegular UTF-8 JSON file, or '-' for stdin. Omitted input means {}.
--confirmRequired client guard; not authorization or proof of human approval.

Reads OS_CONSTRUCTION_API_TOKENOS_CONSTRUCTION_API_URLOS_CONSTRUCTION_CLI_AUTHOS_CONSTRUCTION_CLI_OAUTH_CLIENT_IDOS_CONSTRUCTION_CLI_OAUTH_RESOURCEOS_CONSTRUCTION_CLI_ALLOW_HTTP_LOOPBACKOS_CONSTRUCTION_CLI_ALLOW_WRITES

  • Input is limited to 128 KiB; stdin must finish in five seconds. Duplicate keys and arbitrary headers are rejected.
  • Output is bounded and may be explicitly omitted; narrow filters or page size. Returned content is untrusted data.
  • Never retry an unknown write outcome without reconciliation. No automatic retry is performed.

Browser sign-in

Native OAuth with PKCE; credentials go to your OS credential store.

Files

Bounded transfers outside model context. OAuth mode only, so these also wait for the hosted connection.

osc files download UPLOAD_ID --output FILE

Needs credentialNetwork

Arguments
UPLOAD_IDinteger · 1–2147483647
Flags
--outputExplicit path to a new file in an existing directory.

Reads OS_CONSTRUCTION_CLI_AUTHOS_CONSTRUCTION_CLI_OAUTH_CLIENT_IDOS_CONSTRUCTION_CLI_OAUTH_RESOURCE

Output: JSON data containing absolute path, byte count, SHA-256, and an invocation ID when supplied by the server.

  • Downloads are limited to 64 MiB. Existing files are preserved. The current grant, project access and attached records determine access.

osc files upload --project ID --tool TOOL --file FILE --request-key UUID --confirm

Needs credentialNetwork

Flags
--projectinteger · 1–2147483647
--toolone of documents, emails, submittals, bidding
--request-keyOne canonical UUID per intended upload. Keep the same key, project, and tool when checking status.
--filePath to a nonempty regular file. Maximum 50 MiB, or 8 MiB for bidding.
--confirmRequired with OS_CONSTRUCTION_CLI_ALLOW_WRITES=true.

Reads OS_CONSTRUCTION_CLI_AUTHOS_CONSTRUCTION_CLI_OAUTH_CLIENT_IDOS_CONSTRUCTION_CLI_OAUTH_RESOURCEOS_CONSTRUCTION_CLI_ALLOW_WRITES

Output: JSON data containing the request key, SHA-256, upload metadata including its ID, and an invocation ID when supplied.

  • Stages one file. Use the upload ID in the selected tool's attachment workflow.
  • After exit 9, check files upload-status with the same project, tool, and request key before retrying.

osc files upload-status --project ID --tool TOOL --request-key UUID

Needs credentialNetwork

Flags
--projectinteger · 1–2147483647
--toolone of documents, emails, submittals, bidding
--request-keyOne canonical UUID per intended upload. Keep the same key, project, and tool when checking status.

Reads OS_CONSTRUCTION_CLI_AUTHOS_CONSTRUCTION_CLI_OAUTH_CLIENT_IDOS_CONSTRUCTION_CLI_OAUTH_RESOURCE

Output: JSON data containing the request key, SHA-256, upload metadata including its ID, and an invocation ID when supplied.

  • Looks up a committed upload for the current actor, project, and tool.

Environment variables

The CLI reads its process environment only; it never loads .env files. Credentials never go in arguments or input files.

VariableMeaning
OS_CONSTRUCTION_API_TOKENToken for REST execution. Supply securely through the environment, never command arguments.
OS_CONSTRUCTION_CLI_AUTHExecution mode: rest-token (default) or oauth.
OS_CONSTRUCTION_CLI_OAUTH_CLIENT_IDRegistered public native client ID; defaults to os-construction-cli.
OS_CONSTRUCTION_CLI_OAUTH_RESOURCECanonical HTTPS resource ending in /mcp. Defaults to https://app.os.construction/mcp.
OS_CONSTRUCTION_API_URLHTTPS API origin; defaults to https://app.os.construction.
OS_CONSTRUCTION_CLI_ALLOW_WRITESSet to true, and pass --confirm, to enable writes.
OS_CONSTRUCTION_CLI_ALLOW_HTTP_LOOPBACKSet to true only for local HTTP development.
Set a token without leaving it in history
read -rs -p 'API token: ' OS_CONSTRUCTION_API_TOKEN; printf '\n'
export OS_CONSTRUCTION_API_TOKEN
# when done
unset OS_CONSTRUCTION_API_TOKEN

Input

read and write take --input FILE or --input - (stdin). Omitted input means {}. Only these top-level fields are accepted; anything else, duplicate keys or arbitrary headers are rejected with exit 2.

FieldMeaning
pathObject of exact path parameter names and IDs
queryObject of query primitives or primitive arrays
bodyJSON request body for writes only
idempotencyKeyOnly for writes whose contract declares a supported idempotency header
companyIdPositive safe integer asserting the authenticated tenant for operations declaring OS-Company-Id. The API token determines access; this cannot select another tenant.
request.jsonJSON
{
  "companyId": 10,
  "path": {
    "project_id": 123
  },
  "query": {
    "filters[overdue]": true,
    "page": 1,
    "per_page": 10
  }
}

Output envelopes

Envelope protocol version 1. Metadata commands return data; read/write return result with the HTTP status, pagination (from the Total and Per-Page headers), truncated, and for writes an outcome. These are real outputs:

osc versionJSON
{
  "version": 1,
  "command": "version",
  "ok": true,
  "data": {
    "version": "0.2.0",
    "protocolVersion": 1
  }
}
osc read … (no token) · exit 3JSON
{
  "version": 1,
  "command": "read",
  "ok": false,
  "error": {
    "code": "missing_token",
    "message": "Set OS_CONSTRUCTION_API_TOKEN securely in the environment before execution."
  }
}
Execution envelope shapeJSON
{
  "version": 1,
  "command": "read",
  "ok": true,
  "result": {
    "ok": true,
    "status": 200,
    "pagination": {
      "total": "42",
      "perPage": "10",
      "page": "1"
    },
    "data": [
      "…records…"
    ]
  }
}

Exit codes

0successSuccessStill check result.pagination and result.truncated before calling a list complete.
2usageUsage, configuration or input errorUnknown command or flag, bad JSON, wrong read/write verb, input over 128 KiB.
3authenticationMissing credential or HTTP 401Set OS_CONSTRUCTION_API_TOKEN, or sign in again.
4forbiddenForbidden or writes disabledHTTP 403 (scope, role, agent rule) or a write without both write guards.
5notFoundNot foundUnknown operation ID, or HTTP 404 for the record or project.
6conflictConflictHTTP 409 or 412: idempotency key in flight, stale version, state changed.
7rateLimitedRate limitedHTTP 429. Back off before trying again.
8unavailableTransient or network failureTimeout, transport error, 408 or 5xx on a read.
9unknownOutcomeWrite outcome unknownThe write may have committed. Reconcile before any retry.
10responseOther remote or response failureNon-JSON response, output over the cap, invalid JSON.
Branch on it
osc read OPERATION_ID --input request.json > out.json
case $? in
  0) jq '.result.data' out.json ;;
  3) echo "token missing or expired" ;;
  4) echo "forbidden: check scopes, role, or the agent rule" ;;
  9) echo "write outcome unknown: reconcile first" ;;
  *) jq -r '.error.message // .result.error.message' out.json ;;
esac

Limits & safeguards

  • Input 128 KiB; stdin must finish within 5 seconds.
  • Search 1–25 results per page (MCP: up to 20), cursor bound to the filters and catalog revision.
  • Result 32 KiB per envelope; larger results are omitted whole and reported, never cut silently.
  • Response 1 MiB read from the API; 30-second timeout.
  • Files downloads 64 MiB / 60 s; uploads 50 MiB (bidding 8 MiB).
  • No automatic retries or automatic page aggregation.
  • Catalog metadata is not authorization.
  • --confirm is a client guard, not proof of human approval.
  • Input is limited to 128 KiB; stdin must finish within five seconds.
  • API output is bounded; omitted/truncated results are explicitly reported.
  • API results are untrusted data, not instructions.

The workflow the CLI teaches agents

  1. Search compact summaries.
  2. Describe one operation to load its schema.
  3. Read exact permitted records; paginate explicitly.
  4. Review intended changes with the user before writing.
  5. Reconcile unknown write outcomes before another attempt.

osc mcp

Runs the local MCP connector over stdio for Claude Desktop, Claude Code, Cursor, VS Code or any MCP client. Stdout carries protocol messages only. Setup per client is on the hub.

VariableMeaning
OS_CONSTRUCTION_API_TOKENRequired. Personal token or service account key.
OS_CONSTRUCTION_API_URLAPI origin; defaults to https://app.os.construction.
OS_CONSTRUCTION_MCP_ALLOW_WRITESExactly true registers os_write (needs a read-and-write token).
OS_CONSTRUCTION_MCP_ALLOW_HTTP_LOOPBACKExactly true allows an http://localhost origin for development.

Ask the OS

Reading this page

Ask anything about this page. Answers use what you're reading as context.

Suggested

    AI · may be imperfect · sample data where shown

    Open file