Skip to content
Sapporta

Use the Sapporta CLI

View as Markdown

The Sapporta CLI is a client for a running application. It discovers mounted endpoints and tables, performs generated row operations, calls app-owned routes, and exposes privileged SQL commands when a higher-level interface is not enough.

This guide teaches the normal discover, act, and read-back loop. You can use it for local development checks, deployment smoke tests, operator workflows, and structured input for another program.

Use the project-local Sapporta CLI to <inspect or change something>. Discover
the live table or endpoint first, make the narrowest call that fits, and read
the result back. Do not use SQL if a row or app command covers the operation.

Target the running app

Section titled “Target the running app”

Use the project-local binary so the commands match the installed framework version:

Terminal window
pnpm exec sapporta --help
pnpm exec sapporta endpoints list
pnpm exec sapporta tables list

API-backed commands target http://localhost:3000 by default. A remote app or non-default port needs an explicit URL and, for a protected app, a bearer token. Flags override environment values.

Terminal window
pnpm exec sapporta \
  --api-url https://tasks.example.com \
  --api-token "$SAPPORTA_API_TOKEN" \
  endpoints list

Keep the token outside the repository. It represents one user in one active workspace, so a successful call also identifies the authority used for the result.

Discover, change, and confirm

Section titled “Discover, change, and confirm”

Inspect the task table and a representative row before changing data:

Terminal window
pnpm exec sapporta tables show tasks
pnpm exec sapporta tables sample tasks
pnpm exec sapporta rows list tasks \
  --where '{"status":{"eq":"open"}}' \
  --sort "due_date"

Use the generated row command for an ordinary field update. System-managed fields such as workspace_id, created_at, and updated_at stay out of the payload.

Terminal window
pnpm exec sapporta rows update tasks 1 --values '{"priority":"high"}'
pnpm exec sapporta --output json rows get tasks 1

Use the generic API command for an app-owned operation or report:

Terminal window
pnpm exec sapporta api post /api/tasks/1/complete --body '{}'
pnpm exec sapporta --output json \
  api get /api/reports/project-progress --query '{"project_id":1}'

JSON output is the better boundary for scripts and agents. Table output is more readable during interactive inspection.

An APP_SERVER_UNREACHABLE result is a target or server problem. An auth error is an authority problem. A structured 400 after a row or API call is a request problem. Keeping those failures separate prevents dependency or database changes from masking a bad URL, token, or payload.

The CLI now operates the same mounted application surface as the browser. Its main value is the repeatable read-back loop and machine-readable output, not a second data model. Continue with the agent data console for a full operational workflow or endpoint discovery for an exact contract.

Section titled “Related reference”