Skip to main content
Complete installation, authentication, and context selection before running unattended reads. Prepare the profile in advance; authentication can require user interaction. This guide shows how to capture a Canvas page inventory for another program.

​
Check context, then capture a read

Confirm the active profile, organization and project. These examples use that saved context. Add --json when another program needs to parse the result, then run this shell script:
Successful ordinary JSON commands write their result to stdout and exit 0. This list is an array, so the script parses it before using it. On failure, treat pages.json as unusable even if it exists or contains some data. Keep stderr separate so diagnostics cannot corrupt JSON input. Handled authentication, API, context, and value errors exit 1. With --json, these handled errors are JSON objects on stderr with ok: false and error; API errors may also include status_code and response_body. Command syntax errors generally exit 2 and may be plain text. Do not assume every failure is JSON, or print diagnostics containing sensitive server details into public logs.

​
Select a known field

For a program needing just the effective project ID:
Global --query is a narrow output path selector: it supports keys, dotted fields, and nonnegative list indices, such as items[0].id. It is not JMESPath and does not support filters, wildcards, or arbitrary expressions. Missing keys and invalid indices fail; check that an array is nonempty before selecting its first item. JSON strings remain JSON strings, including quotes.

​
Handle each command’s output contract

--json is a global option placed before the command. It does not turn every command into one JSON document. Canvas JSONL exports and row queries with --format jsonl produce one record per line; Markdown exports produce text; job log streaming produces streamed content. Downloads and other file-oriented commands also need their own contract. Inspect command help and the command reference before piping output to a JSON parser. There is no universal --yes, --non-interactive, or --dry-run option. Use only options advertised by the specific command. Some write commands provide previews; an API preview may still fetch OpenAPI, and a Canvas update preview may read the current page. Verify actual stored state after a write. Local --limit and --offset options often slice a fetched collection. They do not establish that all backend pages were fetched. Record which slices you processed and account for concurrent changes. Interrupted exports or streams can leave partial files; check completion and exit status before promoting them to downstream inputs. A timeout does not prove a mutation failed. Read the resource and reconcile its state before retrying a create, append, or delete. Use bounded retries only when the operation’s semantics make repetition safe; do not add a blanket mutation retry loop. Follow execution workflows to monitor remote work and troubleshooting to diagnose failures. For longer workflows with typed results and explicit error handling, use the Python SDK and its error guidance.