CLI quickstart

The Gavana CLI is a JSON-first client for the same Canvas API this section documents. Every command maps onto an operation you can see in Resources — and gavana api lets you call any operation raw, including the handful with no dedicated command.

That makes it two useful things at once: a fast way to explore the API before you write code, and a way to script against it without writing a client at all.

Confirm your setup

gavana auth status

{
  "authenticated": true,
  "authType": "agent",
  "email": "you@example.com",
  "scopes": ["canvas:read", "canvas:write"],
  "agentLabel": "Quickstart"
}

This is GET /auth/status verbatim. Everything the CLI prints is the API response, which is what makes it a good exploration tool — what you see is what your own client will get.

If something is misconfigured, gavana doctor checks the profile, base URL, and credential in one shot.

Commands map to operations

Each generated resource page repeats this mapping per operation under CLI equivalent, so you can move in either direction.

Three operations have no dedicated command — POST /canvases/{canvasId}/workflows, POST /images/import, and GET /assets/preview. Use gavana api for the first two; preview URLs are handed to you inside asset and job responses.

The same flow as the other quickstarts

gavana canvas list --limit 10

gavana canvas get canvas:product-launch

REV=$(gavana canvas get canvas:product-launch | jq -r '.canvas.revision')
 
gavana api POST /canvases/product-launch/operations --json "$(jq -n --arg rev "$REV" '{
  validateOnly: true,
  baseRevision: $rev,
  operations: [
    {
      type: "node.create",
      clientId: "client:cli-note",
      node: {
        type: "sticky",
        title: "CLI quickstart",
        position: { x: 0, y: 0 },
        width: 240,
        height: 160,
        metadata: { content: "Written from the CLI quickstart." }
      }
    }
  ]
}')"

gavana canvas apply canvas:product-launch \
  --idempotency-key 'cli-quickstart-note-001' \
  --json '{ "operations": [ … ] }'

gavana api: the raw passthrough

gavana api sends an arbitrary request to the Canvas API using your stored credential and base URL. Paths are restricted to /api/canvas-agent/v1, so you write the path relative to that prefix.

# GET is the default when the first argument is a path
gavana api /auth/status
 
# An explicit method
gavana api GET /canvases --field limit=10
 
# --field repeats; on a GET the fields become query parameters
gavana api GET /models --field capability=image.generate --field provider=openai
 
# On a non-GET the fields become a flat JSON body
gavana api POST /canvases --field title='Concepts' --field canvasType=agent
 
# For anything nested, pass JSON
gavana api POST /canvases/product-launch/operations --json '{
  "baseRevision": "2026-08-04T09:12:44.318726Z",
  "idempotencyKey": "raw-passthrough-001",
  "operations": [
    { "type": "node.move", "nodeId": "node:8f2a91c4", "position": { "x": 400, "y": 0 } }
  ]
}'
 
# DELETE
gavana api DELETE /runs/2c9a1f3e

This is the fastest way to try an operation you are about to implement. It is also the only CLI route to operations with no dedicated command:

# Import a public HTTPS image as a durable canvas node
gavana api POST /images/import --json '{
  "canvasId": "canvas:product-launch",
  "imageUrl": "https://example.com/reference.png",
  "title": "Reference",
  "idempotencyKey": "import-reference-001"
}'

Flags that mirror API fields

These appear on the commands that write, and each maps to a body field you would send yourself:

--webhook-secret-env is a small but good design detail worth copying: the secret never appears in argv, so it never reaches shell history or ps.

Scripting against it

Every command prints JSON to stdout, so jq composes naturally:

# Every accessible canvas handle
gavana canvas list --limit 25 | jq -r '.canvases[].handle'
 
# Image models, sorted by estimated runtime
gavana model list --capability image.generate | jq -r '.models | sort_by(.estimatedSeconds)[] | "\(.handle)\t\(.modelId)\t~\(.estimatedSeconds)s"'
 
# The revision of a canvas, ready to feed into a raw call
gavana canvas get canvas:product-launch | jq -r '.canvas.revision'
 
# Walk every page of assets
CURSOR=''
while :; do
  PAGE=$(gavana asset list --limit 200 ${CURSOR:+--cursor "$CURSOR"})
  printf '%s' "$PAGE" | jq -r '.assets[].handle'
  CURSOR=$(printf '%s' "$PAGE" | jq -r 'if .page.hasMore then .page.nextCursor else empty end')
  [ -n "$CURSOR" ] || break
done

Errors go to stderr as a single JSON object, and the exit code is non-zero:

{ "ok": false, "error": { "code": "forbidden", "message": "This agent token is missing required permissions: canvas:write." } }

So set -e plus a stderr capture is enough for a robust script — you do not need to parse stdout to detect failure.

When to stop using the CLI

The CLI is a great client until you need something it deliberately does not do: custom retry policy, a webhook receiver, long-lived connection pooling, or running inside a service. At that point port your gavana api calls into a real client — the TypeScript quickstart is about eighty lines and has no dependencies.

Next

• Install and log in to the CLI — if you have not yet
• CLI reference — every command and flag
• TypeScript quickstart — the same flow as code
• Platform — the mechanisms the CLI is hiding from you