AI providers

Choosing

canvas-cli needs one AI provider for its assistant, and any of these works. Pick one in the sign-in wizard (canvas-cli login), switch any time with /model in the shell, or set it in the environment.

If you already have GitHub Copilot or a ChatGPT plan, start there: there is no key to manage and usage counts against the plan you pay for. Otherwise any API key works. Cost depends on the model and effort: the default models are the most capable ones, and smaller models and lower effort cost less. Your provider’s pricing page has current rates.

What Needs AI

Anthropic

1. Sign in at console.anthropic.com and open API Keys.
2. Create a key named “canvas-cli” and copy it. It starts with sk-ant-.
3. Run canvas-cli login, choose Anthropic, and paste it. Or set it in the environment:

AI_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...

OpenAI

1. Sign in at platform.openai.com and open API keys.
2. Create a secret key and copy it. It starts with sk-.
3. Choose OpenAI in canvas-cli login and paste it, or:

AI_PROVIDER=openai
OPENAI_API_KEY=sk-...

Google

1. Sign in at aistudio.google.com and choose Get API key.
2. Create a key in a new or existing project and copy it.
3. Choose Google (Gemini) in canvas-cli login and paste it, or:

AI_PROVIDER=google
GOOGLE_API_KEY=...

AWS Bedrock

For people already on AWS. Bedrock uses AWS credentials (IAM access keys, or a Bedrock API key through AWS_BEARER_TOKEN_BEDROCK) instead of a provider API key, and the Claude models must be enabled for your account first.

1. In the AWS console, open Amazon Bedrock → Model access and request the Anthropic models in your region.
2. Create an IAM user or role allowed to call bedrock:InvokeModel and bedrock:InvokeModelWithResponseStream, and access keys for it.
3. Choose AWS Bedrock in canvas-cli login enter the region and keys, and pick a model (or type any model id), or:

AI_PROVIDER=bedrock
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...

AWS_SESSION_TOKEN works for temporary credentials, and AWS_BEARER_TOKEN_BEDROCK for bearer token authentication. canvas-cli reads keys from these variables or from login only; AWS_PROFILE, ~/.aws/credentials, and SSO sessions are not used. Model ids start with us.anthropic.; use a global., eu., jp., or au. prefix for other regions.

Subscriptions

canvas-cli can run on a GitHub Copilot or ChatGPT plan through the vendor’s own command-line tool. There is no API key: the vendor’s CLI holds your login, and usage counts against your plan. You install the CLI yourself; canvas-cli finds it on your PATH or in the usual global install folders.

GitHub Copilot

Works with Copilot Free, and with the free Copilot Pro that students get through GitHub Education.

npm install -g @github/copilot
copilot login

Then choose GitHub Copilot in canvas-cli login, which checks that the CLI is installed and offers to run copilot login for you. The default model, auto, lets Copilot pick; any model id the Copilot CLI accepts can be entered as a custom model.

ChatGPT via Codex

npm install -g @openai/codex
codex login

Then choose ChatGPT via Codex. The model list shows the models your plan offers, read from Codex’s own model catalog, and the default runs whatever Codex currently uses by default, shown by name in the header.

How it runs

For each request, canvas-cli starts the vendor’s CLI in non-interactive mode, in an empty temporary folder. Copilot’s own tools for running commands, reading and writing files, and fetching the web are removed. Codex runs in a read-only sandbox with web search off, without saving a session, and ignoring your own Codex config. The Canvas tools are offered over a local connection that only accepts a secret token created for that one request, so every Canvas tool still runs inside canvas-cli. See Privacy.

A few differences from API keys:

• Subscription providers are never picked automatically; choose them in the wizard or set AI_PROVIDER.
• Copilot streams answers as they are written; Codex shows each message once it is complete.
• The 30-step tool budget is not enforced on these providers.

Models

The sign-in wizard and /model list the models for each provider, with a Custom option for any other id. For Bedrock, the wizard asks you to type the model id; /model has the list. To choose one without the picker, set AI_MODEL:

AI_MODEL=claude-sonnet-5

/model key replaces the stored API key, or AWS credentials for Bedrock, without going through the rest of the setup.

Effort

Most models can think before they answer, and the effort level sets how much. Higher effort is slower and costs more, and helps most on long documents and tricky comparisons.

Choose it with /model effort, which only offers the levels the current model supports, or set AI_EFFORT. A level the model does not support rounds up to the nearest one it does, or down to its highest: xhigh becomes max on Claude Sonnet 4.6 and high on Gemini. Copilot and Codex receive the level exactly as you set it.

AI_EFFORT=high

Auto-Detection

If AI_PROVIDER is not set and no provider was chosen at sign-in, canvas-cli uses the first API key it finds, in this order: ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY. Bedrock, Copilot, and Codex are never detected this way.

AI_PROVIDER accepts a few aliases: gemini for Google; aws-bedrock and amazon-bedrock for Bedrock; github-copilot for Copilot; and chatgpt or openai-codex for Codex. Values are case-insensitive. An unrecognized value turns AI off rather than guessing, and so does choosing Anthropic, OpenAI, or Google without its key.