CLI permissions and troubleshooting
Understand API authorization, exit codes, partial results and safe recovery.
Partly in the app today. Items marked Planned are not built yet.
On this page
- Interpret exit codes
- Common problems
- Coverage and release status
- Native OAuth status and revocation
- Stored-upload download permissions
- Company setup access
- Native file staging permissions
- Workflow authorization and record visibility
- Specifications, Notifications and Managed Equipment
- Budget, Change Orders and WBS boundaries
- Company governance, photo metadata and bidding
Default REST-token mode sends the configured user’s API token to the approved REST origin. Optional native OAuth mode uses a separately approved grant through the hosted invocation boundary. Live handlers enforce applicable scopes, tenant, project, record and workflow permissions. Discovery exposes metadata; it does not establish permission to execute every listed operation. Changing a project ID does not grant access. Input companyId is a positive safe integer assertion for operations declaring OS-Company-Id, not a way to select another tenant; the API must reject a mismatch.
Keep credentials in protected process environment settings. Do not place them in prompts, input files, command arguments or recordings. A browser login alone does not change REST-token mode; native OAuth must be explicitly selected.
Interpret exit codes
| Exit | Meaning | Next action |
|---|---|---|
| 0 | Success | Inspect pagination and truncation. |
| 2 | Usage/configuration/input error | Check help and describe. |
| 3 | Missing credential or unauthorized | Check secret injection, expiry and revocation. |
| 4 | Forbidden or write gate disabled | Review current access and write intent. |
| 5 | Not found | Check the permitted target; absence may be concealed. |
| 6 | Conflict | Read current state and resolve the conflict. |
| 7 | Rate limited | Reduce work according to service policy. |
| 8 | Transient/network failure | Investigate before resuming. |
| 9 | Unknown mutation outcome | Reconcile live state before retrying. |
| 10 | Other remote/response failure | Inspect the structured error. |
In PowerShell read $LASTEXITCODE; in Bash read $? immediately after the command. Parse the JSON envelope as well. An exit-zero first page does not mean the full collection was retrieved.
Common problems
If help succeeds but reads fail, remember that metadata commands never authenticate. If an operation is absent, run coverage and search by module or method. Do not guess an operation ID or substitute an arbitrary URL.
For input errors, inspect exact path names, body wrapper and query fields in describe. Input is bounded to 128 KiB; stdin must complete within five seconds. For stale discovery cursors, restart search without a cursor.
If JSON parsing sees package-manager text, use the direct Node command from the setup guide. Keep stderr separate from stdout.
Writes require OS_CONSTRUCTION_CLI_ALLOW_WRITES=true and --confirm. Those guards cannot bypass an API denial. Missing scope, project permission, module enablement, workspace restrictions and business policy can each deny an operation.
Coverage and release status
The preview covers cataloged JSON operations with matching contracts and route exports. General multipart uploads, other binary responses, missing contracts and excluded definitions remain tracked gaps; the bounded stored-upload download path below is separate from the JSON catalog. Catalog revision 2b7478125d87ef8dead46a61 contains 2,191 operations and 386 exclusions, including the budget snapshots, JSON transmittals and the company setup reference operations. Run coverage to check your installed revision; inclusion does not prove every endpoint has been exercised through the CLI.
The CLI is published on npm as @os-construction/cli, and native browser OAuth is implemented. The hosted connection is live in preview (read-only). Full live authorization checks and authenticated recordings remain release work.
Native OAuth status and revocation
osc auth status reads local profile metadata: resource, client, scopes and access expiry. It makes no server request and does not prove the saved grant is still active. A revoked grant may remain visible locally until logout or another access attempt.
osc auth logout revokes the saved grant remotely, then clears local credentials. If revocation cannot complete, logout fails and retains the local record. Review Account > Connected apps to revoke access on the server and retry logout. Log out before replacing an existing connection; changing the resource or client ID does not revoke the old profile.
The CLI refreshes expiring credentials under a profile lock. If refresh fails or its outcome is uncertain, the previous credentials are cleared to avoid replay; sign in again when prompted. Writes still require both local write enablement and --confirm, and unknown mutation outcomes still require reconciliation.
Windows DPAPI storage is locally verified. Linux requires a working Secret Service and /usr/bin/secret-tool; its live store integration remains unverified. macOS storage is unavailable. An unavailable store reports failure with no plaintext fallback. The existing REST-token mode remains available for runners without browser or OS-store support.
Stored-upload download permissions
osc files download <upload-id> --output <path> requires OS_CONSTRUCTION_CLI_AUTH=oauth and a native OAuth connection. Obtain the upload ID only from the exact own-site /rest/v1.0/uploads/<id> exposed by an authorized owning-tool response. The command accepts neither an arbitrary URL nor a server filesystem path; an attachment ID is not interchangeable with an upload ID.
The request to /mcp/files/<id> authenticates again and checks tenant/project/user access and the actual owning records. An attached upload needs the owning tools’ scopes and record access. uploads:read is the scope requirement for an unbound upload only, alongside normal access checks; it does not override attachment permissions. Missing and inaccessible files may both appear unavailable.
The limit is 64 MiB and 60 seconds, with no range/resume or automatic retry. Choose an explicit new output file in an existing writable directory. Existing destinations are preserved, and an incomplete transfer is not published as the output file. JSON reports the saved path, bytes, SHA-256 and optional invocation receipt; the payload is not streamed into stdout. Use a new path after an output conflict, and review access rather than broadening credentials after a denial.
Optional hosted os_file_info returns metadata, a fixed URL and a receipt only. The URL is not public or presigned: a new download still needs bearer authentication and current access. The rollout requires the OAuth, hosted MCP and native CLI flags. S3 requires an explicitly configured strict streaming adapter; live S3 is unverified. Other binary and multipart workflows remain incomplete, and this feature does not change the JSON catalog counts.
Company setup access
The company_admin reference workflow uses the exact path.company_id of the authorized workspace. Reads require admin:read. Writes require admin:write plus the user’s current company capability for the action and workspace restrictions; the scope alone does not grant an administrator role. Normal CLI write enablement and --confirm still apply. Read a bounded collection and the target record before proposing a mutation. See the company setup workflow.
Native file staging permissions
Native file staging is a separate OAuth transfer boundary for documents, emails, submittals and bidding. It requires the exact <tool>:write scope plus live project access and tool capability. Upload POST also requires OS_CONSTRUCTION_CLI_ALLOW_WRITES=true, --confirm, server write enablement and the OAuth, hosted MCP and native CLI rollout flags. Status GET continues when writes are disabled but still enforces current scope and capability.
Staging returns an unbound upload, not an attached business record. A later supported attach operation has its own permissions and can also require uploads:read. Limits are 50 MiB or the deployment’s lower ceiling; bidding is restricted to 8 MiB PNG/JPEG/PDF. Stored bytes remain outside model context. Scoped local PostgreSQL and CLI checks cover staging and status; they do not establish production availability or comprehensive storage-provider coverage.
Workflow authorization and record visibility
Action Plans, Commitments and Documents operations retain live project and record checks. A plan sign-off requires authorization for the actual actor; neither a broad scope nor a supplied user ID permits signing for someone else. Commitment change-order drafts do not imply approval, execution or payment authority. Document staging, attachment, version review and ACL checks are distinct steps; transferred bytes do not override folder or document access. Confirm restore availability and its authorization through the installed catalog before use.
Specifications, Notifications and Managed Equipment
The new tranche adds 12 Specifications, 8 Notifications and 8 Managed Equipment operations. Discover specifications, notifications or equipment, then describe a result and check live project/company/record access. Expected module read/write scopes do not replace backend permissions: specification recycle/restore requires delete permission, notification recipient settings require notifications admin even for a read, and equipment mutation permissions depend on the exact handler (for example, admin for operational status).
The inbox is the caller’s own currently visible notifications. The path’s project is authorization context, not an inbox project filter; rows may refer to other accessible projects. Use each returned row’s project ID when summarizing. Preferences and mark-read actions are recipient-specific. A summary or URL does not authorize a linked-record read, and a page is not an all-user audit. Follow the detailed workflow and exact catalog examples. Catalog coverage is not exhaustive live verification or public release.
Budget, Change Orders and WBS boundaries
Preview 9 adds 13 Budget control/forecast, 8 Change Orders markup/configuration/tax and 9 WBS operations. Discover budget, change_orders or wbs, then describe the exact operation. Scope is determined by the handler: Change Events posting history is in the Budget catalog module but requires change_events:read and live Change Events view permission. Other read/write scopes do not replace project/company roles or approval authority.
Private SOV line-item and markup details preserve record visibility. Inherited WBS definitions can be visible to a project without granting permission to mutate the owning company’s definitions. Line-item-type DELETE remains excluded from the executable catalog as a missing contract. Its underlying hard-delete handler can leave dangling scalar or JSON accounting references; no comprehensive referential-integrity guard is established. Catalog exclusion is the connector safety barrier, so keep this operation outside agent workflows until integrity checks are implemented and verified. Use the exact CLI examples and review steps. Catalog inclusion is not exhaustive live verification or public release.
Company governance, photo metadata and bidding
Preview 10 covers company insurance and permission-template assignment, photo tag/comment metadata, and credential-free staff bidding invitation/outbox metadata. Discovery does not grant access: verify the exact company/project, current record visibility, operation scope and live role. Template assignment changes access and requires review of the target user and permissions. Photo metadata does not authorize image-byte access.
Invitation writes record data only; no email is dispatched and no raw invitation token is exposed. Do not describe a recorded invitation as sent or delivered. Bidding recycle PATCH is soft-delete, not restore, and retains mutation safeguards. Follow the detailed workflow. This workflow was added at catalog revision 4c554e59a9999629a47407bf; run coverage for the installed revision’s counts. This is not a production release claim.
Keep exploring
Related across os.construction
- DocsWork with the MCP previewUse discovery, schemas, bounded reads, and reviewed writes to work with construction records through the local MCP preview.
- DocsMCP permissions and troubleshootingUnderstand which identity the MCP preview uses, how API permissions apply, and how to handle failures without broadening access.
- BlogConnecting an AI assistant to your construction data: a permissions-first checklistAI assistants can now read and act on project records through connectors such as the Model Context Protocol. Before you connect one to RFIs, commitments or AP, decide whose credential it uses, what it can see, whether it can write, who approves, and how you'll know what it did.
- GlossaryModel Context Protocol (MCP)An open protocol that lets an AI application discover and call tools and read data from other systems through a standard connector.
- GlossaryAI AgentSoftware that uses an AI model to carry out multi-step tasks, like reading documents, checking data and drafting actions, toward a goal.
- Blogos.construction is open for trialsThe app is live at app.os.construction. Start a 14-day free trial: project management and project financials today, with separate company accounting workflows and planned AI agents. Here's exactly what's live and what isn't.
Was this helpful?
Run it on your own project.
Start a 14-day free trial. Want a say in what ships next? Join the founding program.
14-day free trial. Pricing for paid plans isn't set yet. Talk to us. Already have an account? Sign in →