CLI overview
Install @grid82/cli, sign in with OAuth or GRID82_TOKEN, read global flags and exit codes, pipe files, and run grid82 mcp.
The @grid82/cli (grid82) exposes every Studio Builder API and Runtime App API operation as a typed terminal command built for both interactive use and CI/agent automation. Requires Node.js 22.12 or later.
Install or run directly
npm install --global @grid82/cli
grid82 --versionnpx @grid82/cli --versionSigning in and profiles
Use OAuth in interactive terminals, device code login in headless environments, or GRID82_TOKEN in CI pipelines:
# Sign in to Studio in your browser
grid82 auth login
# Sign in to an app suite in your browser
grid82 auth login --target https://your-suite.grid82.app --plane app
# Headless SSH / container device flow
grid82 auth login --target https://your-suite.grid82.app --plane app --device
# Inspect active profile and identity
grid82 auth status
# Named profiles for multiple suites or environments
grid82 auth profiles
grid82 records list tbl_8fj3kq2wmv5d --profile prodDesktop logins store credentials in your OS keychain (with profile state saved cleanly without printing tokens).
Command structure and global flags
Every API operation maps directly to <resource> <action>. Global flags can appear either before or after the subcommand:
grid82 records list tbl_8fj3kq2wmv5d --view-id viw_e4ks9mz2bh7w
grid82 records get tbl_8fj3kq2wmv5d rec_4nqw8e2hzk7s --json
grid82 records create tbl_8fj3kq2wmv5d --records '[{"Name":"Northwind Renewal","Amount":48000}]'
grid82 files upload tbl_8fj3kq2wmv5d --file ./contract.pdf --record-id rec_4nqw8e2hzk7s
grid82 rules simulate app_5mg8rw2kx4tn --roles rol_v6nh3ta8rk2e --table-id tbl_8fj3kq2wmv5d --op readGlobal flags and environment variables
| Flag | Environment variable | Purpose |
|---|---|---|
--output <mode>, --json | GRID82_OUTPUT | json | table | ndjson (defaults to json automatically when stdout is piped or non-TTY) |
--profile <name> | GRID82_PROFILE | Switch between saved credential profiles |
--studio <url> | GRID82_URL | Target a specific Studio URL for this call |
--app <url> | GRID82_URL | Target a specific Runtime app URL (https://{suite}.grid82.app/{app}) |
--no-retry | Disable automatic retries on 429 and 5xx responses | |
--timeout <seconds> | Per-request timeout in seconds (default 60) |
Reading files and raw requests
- File arguments (
@path). Pass@filenameto read bodies or code directly from disk (or@-for stdin), e.g.,--body @payload.jsonor--source @workflow.ts. - Confirmation flag. Destructive schema/app deletes require
--confirm "Exact name". - Raw API escape hatch.
grid82 api GET /v1/organizationsissues any authenticated HTTP request against the active target. - Stdio MCP bridge.
grid82 mcp(orgrid82 mcp --codefor Code Mode) bridges newline-delimited JSON-RPC on stdin/stdout to your remote MCP server for clients that only launch local processes. - Diagnostics and completion. Run
grid82 doctorto verify CLI version, active credential, endpoint/health, and clock skew, orgrid82 completion zsh|bash|fishfor shell completions.
Exit codes
Non-zero exit codes categorize failures cleanly for shell scripts and agents while writing the structured API error JSON to stderr:
| Exit code | Name | Meaning |
|---|---|---|
0 | OK | Request succeeded |
1 | API_ERROR | Server 5xx, network, or transport error |
2 | USAGE | Validation error (422) or invalid CLI flags |
3 | AUTH | Unauthenticated (401) or forbidden (403) |
4 | NOT_FOUND | Resource missing or outside your scope (404) |
5 | RATE_LIMITED | Rate limit reached (429) |
6 | CONFLICT | Optimistic concurrency or idempotency conflict (409) |
7 | PLAN | Plan limit or AI/workflow credit cap reached (402) |