Skip to main content

Stage CLI Reference

All Stage CLI commands are available under the shift-cli stage namespace (or as the standalone stage binary). Sessions are identified by Convex session IDs.

Global Flags​

FlagDescription
--jsonOutput structured JSON (for agent consumption)
-q, --quietSuppress stdout, exit codes only
-u, --url <url>Override Convex URL
--self-hostedForce self-hosted Convex mode
--cloudForce Convex Cloud mode

Environment Variables​

VariableDescription
CONVEX_URLConvex Cloud deployment URL
CONVEX_SELF_HOSTED_URLSelf-hosted Convex backend URL
CONVEX_SELF_HOSTED_ADMIN_KEYAdmin key for self-hosted Convex
STAGE_URLStage frontend URL (for session links)

Core Commands​

Create a new session​

shift-cli stage new

JSON output:

shift-cli stage new --json
{
  "id": "k77abc123def"
}

Write a file​

Write from a local file or stdin to a remote path in the session:

# From a local file
shift-cli stage write /app/App.tsx ./App.tsx -s <session-id>

# From stdin
cat App.tsx | shift-cli stage write /app/App.tsx -s <session-id>

Read a file​

shift-cli stage read /app/App.tsx -s <session-id>

List files​

shift-cli stage ls -s <session-id>
shift-cli stage ls /app -s <session-id>

Trigger a render​

# Default entry point (/app/App.tsx)
shift-cli stage render -s <session-id>

# Custom entry point
shift-cli stage render /app/Main.tsx -s <session-id>

Get session status​

shift-cli stage status -s <session-id>

JSON output:

shift-cli stage status -s <session-id> --json
{
  "session": {
    "createdAt": 1709640000000,
    "lastAccessedAt": 1709640060000
  },
  "render": {
    "entry": "/app/App.tsx",
    "version": 1,
    "error": null,
    "renderedAt": 1709640060000
  },
  "files": [
    { "path": "/app/App.tsx", "version": 1, "size": 57 }
  ]
}

Push a directory​

Push an entire local directory to a session and optionally trigger a render:

# Push and auto-render
shift-cli stage push ./my-app /app -s <session-id>

# Push with custom entry point
shift-cli stage push ./my-app /app -s <session-id> -e /app/Main.tsx

# Push without rendering
shift-cli stage push ./my-app /app -s <session-id> --no-render

If the Stage app is already linked to a GitHub repository and local git metadata matches that app, stage push will also checkpoint and push local git changes before uploading to Stage. Git sync failures are emitted as warnings and do not block the Stage deploy.

List published apps​

shift-cli stage apps
shift-cli stage apps --author user@example.com
shift-cli stage apps --status published
shift-cli stage repo status [app-id]
shift-cli stage repo local
shift-cli stage repo connect [app-id]
shift-cli stage repo disconnect [app-id]

Use stage repo local to inspect .shift/stage-app.config.json, which is written by shift-cli create-app.

Declare Google OAuth scopes​

shift-cli stage scopes:set \
  -s <session-id> \
  --scope https://www.googleapis.com/auth/drive.readonly \
  --scope https://www.googleapis.com/auth/spreadsheets

This stores the requested scopes in Convex so the Stage Google OAuth flow can request them later.

Show Convex configuration​

shift-cli stage config

Onboard (add instructions to CLAUDE.md)​

shift-cli stage onboard

Delegated local test flows are exposed as top-level shift-cli commands rather than shift-cli stage ... subcommands:

shift-cli token create --session <session-id> --ttl 30m --json
shift-cli token list --json
shift-cli test bootstrap --session <session-id> --redirect /s/<session-id> --json

These are intended for Playwright and @the-shift/sdk/testing workflows.