Esc

↑↓ move↵ openIndex · Pagefind
Agents / Set up the CLI preview

Set up the CLI preview

Install the osc command, find operations without signing in, and run authorized reads with a personal token or browser sign-in.

Preview

Partly in the app today. Items marked Planned are not built yet.

On this page

The CLI lets agents and scripts search for operations, load one input contract and execute an authorized REST request. Every command prints one JSON envelope. It shares discovery and request safeguards with the MCP connector, and osc mcp runs that connector for MCP clients.

Quick start

Requires Node.js 24 or newer.

npx -y @os-construction/cli help
npx -y @os-construction/cli operations search --query rfis --method GET --limit 5

To run authorized commands, create a token in Account > AI assistants > Personal API tokens (keep Read-only unless you need changes), put it in OS_CONSTRUCTION_API_TOKEN through your shell or secret manager, and run osc read. You can also sign in through the browser instead with osc auth login; see Native browser sign-in.

Run from source (contributors)

Everyone else should use the npm package above. With a trusted repository checkout and Node.js 24 or newer, run from app:

npm ci
npm run mcp:catalog
node --import tsx scripts/osc.ts help
node --import tsx scripts/osc.ts help read
node --import tsx scripts/osc.ts coverage
node --import tsx scripts/osc.ts operations search --query rfis --method GET --limit 5

On Windows PowerShell, use npm.cmd when script execution policy blocks npm.ps1. Use the direct Node command in automation to keep package-manager banners out of JSON output.

Discovery and focused help need no token and make no API request. Use help operations search or operations search --help to load only search options; read --help explains execution input without reading stdin. Search results describe the catalog; they do not prove access to records. Describe a returned operation ID before executing it:

osc operations describe OPERATION_ID

Configure execution

Create a personal token in Account > AI assistants, or use one your administrator issued for your own user. Inject it through your runner’s protected environment, never through an agent prompt or command argument.

Variable Purpose
OS_CONSTRUCTION_API_TOKEN User API token for default REST-token execution.
OS_CONSTRUCTION_CLI_AUTH rest-token by default; oauth selects native OAuth execution.
OS_CONSTRUCTION_CLI_OAUTH_CLIENT_ID Registered native client ID for OAuth; defaults to os-construction-cli.
OS_CONSTRUCTION_CLI_OAUTH_RESOURCE Canonical HTTPS URL ending in /mcp; defaults to https://app.os.construction/mcp.
OS_CONSTRUCTION_API_URL Approved API origin; defaults to https://app.os.construction.
OS_CONSTRUCTION_CLI_ALLOW_WRITES Leave unset for reads; exact true enables mutation commands.
OS_CONSTRUCTION_CLI_ALLOW_HTTP_LOOPBACK Explicit opt-in for local HTTP development only.

The CLI reads process environment settings and does not automatically load application .env files. A browser session does not change default REST-token execution. OAuth requires the explicit setup below.

Native browser sign-in

Browser sign-in works against the live hosted connection with the approved CLI client (os-construction-cli, the default). The CLI binds a temporary local port for the callback. The server must set MCP_OAUTH_ENABLED=true, MCP_HOSTED_ENABLED=true and MCP_CLI_OAUTH_ENABLED=true for native invocation.

The defaults target https://app.os.construction/mcp with client os-construction-cli:

osc auth login --scopes 'rfis:read'
osc auth status
export OS_CONSTRUCTION_CLI_AUTH=oauth

PowerShell uses the same commands with environment assignments:

osc auth login --scopes 'rfis:read'
osc auth status
$env:OS_CONSTRUCTION_CLI_AUTH = 'oauth'

For a test environment, also set OS_CONSTRUCTION_CLI_OAUTH_RESOURCE to its canonical https://.../mcp address, and OS_CONSTRUCTION_CLI_OAUTH_CLIENT_ID if that environment registered a different client.

For source usage, replace osc with node --import tsx scripts/osc.ts from app. Login opens the system browser for sign-in and explicit consent; it automatically includes catalog discovery. It does not switch execution mode by itself. With OS_CONSTRUCTION_CLI_AUTH=oauth, the same read/write commands use the saved grant through the hosted invocation boundary. REST-token mode remains the default.

Windows credentials use user-bound DPAPI protection, verified locally. Linux Secret Service support is implemented but live OS-store verification remains pending; macOS storage is unavailable. There is no plaintext fallback. The hosted connection is live in production as a read-only preview.

Use osc auth logout to revoke the saved grant and clear local credentials after successful revocation. See connection status and revocation for failure handling.

Read a permitted project

Create request.json using the path and query names in describe. For a collection that declares these fields:

{"companyId":10,"path":{"project_id":123},"query":{"page":1,"per_page":20}}

Replace 10 with your authenticated company and 123 with an approved test project and use a discovered GET operation:

osc read OPERATION_ID --input request.json

Input may contain path, query, body, idempotencyKey and companyId only. --input - reads stdin; input is limited to 128 KiB and stdin must complete within five seconds. Arbitrary headers, URLs, cookies and credentials in input are rejected.

For operations declaring OS-Company-Id, supply companyId as a positive safe integer when required by describe. It asserts the tenant already authorized by your token; it cannot select another company or grant access. Arbitrary headers remain unsupported. Direct-upload input support still requires live workflow verification.

Each command produces one JSON envelope on stdout. Metadata is in data; execution is in result. Diagnostics go to stderr. Inspect result.pagination and result.truncated before claiming a complete result.

Continue with CLI workflows and CLI permissions and troubleshooting.

Save an authorized stored upload

In native OAuth mode, first read the owning record and confirm that its response exposes the exact own-site path /rest/v1.0/uploads/<id>. Use that upload ID, not an attachment/document ID or an external URL. With 123 replaced by the authorized upload ID:

osc files download 123 --output ./review-copy.bin

Choose a new destination in an existing writable directory. The command never overwrites an existing file and emits JSON with the saved absolute path, byte count, SHA-256 and optional invocation receipt. It does not print file bytes into the model’s context. The transfer is limited to 64 MiB and 60 seconds and independently checks the current grant and owning-record permissions.

See download permissions and limits before adding this step to an agent workflow.

Install globally

npm i -g @os-construction/cli
osc version
osc help

Contributors can build the same package from a repository checkout with npm --prefix app run cli:build, then npm pack in tools/cli.

Use npm.cmd and osc.cmd on Windows when script policy requires them. The package requires Node.js 24 or newer and has no runtime npm dependencies; the MCP SDK used by osc mcp is compiled into the single executable. The source command and packaged osc share command arguments and environment settings.

Review company setup

For company reference records, start with operations search --module company_admin --query departments --method GET --limit 5. Describe the returned collection operation, then read a bounded page using the exact authorized workspace company_id. Use admin:read for the review; company writes require additional live permission and admin:write. Follow the company setup reference workflow before changing departments, offices, regions, types, trades or stages.

Candidate file staging

Native OAuth file staging for documents, emails, submittals and bidding is documented in the staging workflow. It stages an unbound upload for a separate supported attachment operation, with explicit write guards and bounded transfers. Scoped local PostgreSQL and CLI checks cover candidate staging and status; production availability and broader storage-provider coverage remain unverified. Existing JSON catalog counts are unchanged.

For the candidate Action Plans, Commitments and Documents tranche, begin with the bounded workflow review. The current catalog includes the new tranche; existing native file guidance and live authorization checks still apply.

Preview 8 adds Specifications, Notifications and Managed Equipment workflows. Use the bounded discovery and permission guidance, including the caller-specific notification inbox behavior.

Preview 9 adds Budget, Change Orders and WBS coverage. Begin with the financial workflow review, including private SOV access, inherited WBS ownership and the catalog exclusion for unsafe line-item-type deletion.

For the preview 10 company governance, Photos metadata and Bidding tranche, begin with the workflow and permission review. Invitation writes record data without dispatching email; recycle PATCH soft-deletes. Run osc coverage to see the catalog revision your installed package carries.

Keep exploring

Related across os.construction

Run it on your own project.

Start a 14-day free trial. Want a say in what ships next? Join the founding program.

Your role (optional)

14-day free trial. Pricing for paid plans isn't set yet. Talk to us. Already have an account? Sign in →

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