---
title: "CLI overview"
description: "Install @grid82/cli, sign in with OAuth or GRID82_TOKEN, read global flags and exit codes, pipe files, and run grid82 mcp."
canonical: "https://grid82.com/docs/developers/cli/overview"
updated: "2026-11-20"
---

# CLI overview

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

```bash title="Install globally"
npm install --global @grid82/cli
grid82 --version
```

```bash title="Run without installing"
npx @grid82/cli --version
```

## Signing in and profiles

Use OAuth in interactive terminals, device code login in headless environments, or `GRID82_TOKEN` in CI pipelines:

```bash
# 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 prod
```

Desktop logins store credentials in your OS keychain (with profile state saved cleanly without printing tokens).

> **Warning**
>
> For environment variable authentication, set **`GRID82_TOKEN`** and **`GRID82_URL`**. The CLI does not read `GRID82_API_KEY` and warns if only that name is set.

## Command structure and global flags

Every API operation maps directly to `<resource> <action>`. Global flags can appear either before or after the subcommand:

```bash
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 read
```

### Global 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 `@filename` to read bodies or code directly from disk (or `@-` for stdin), e.g., `--body @payload.json` or `--source @workflow.ts`.
- **Confirmation flag.** Destructive schema/app deletes require `--confirm "Exact name"`.
- **Raw API escape hatch.** `grid82 api GET /v1/organizations` issues any authenticated HTTP request against the active target.
- **Stdio MCP bridge.** `grid82 mcp` (or `grid82 mcp --code` for 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 doctor` to verify CLI version, active credential, endpoint `/health`, and clock skew, or `grid82 completion zsh|bash|fish` for 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`)   |
