Profiles and settings

Where Things Live

canvas-cli keeps two kinds of state in two places:

Set XDG_CONFIG_HOME to move the first one; it becomes $XDG_CONFIG_HOME/canvas-cli. The folder is readable only by you, and so is every file in it.

Credentials

canvas-cli login stores your Canvas token and any AI keys once, so you never paste them again. Where they go depends on your system:

• macOS: the login Keychain, under the service canvas-cli, one item per profile and secret. No plaintext copy is written, and any old one is removed.
• Linux and Windows, or when the Keychain is unavailable: files under ~/.config/canvas-cli/credentials/, readable only by you.

Setting CANVAS_CLI_CREDENTIAL_BACKEND=file forces the file store on macOS too, which is mainly useful in tests and CI. canvas-cli status tells you which store is in use. Subscription providers store nothing: their login belongs to the vendor’s own CLI.

Profiles

Profiles keep separate Canvas accounts apart, for example your university and a summer program. Each has its own Canvas address, token, and AI settings.

canvas-cli login --profile summer     # set one up
canvas-cli status --profile summer    # check it
export CANVAS_CLI_PROFILE=summer      # use it for the shell and ingest

Everything uses CANVAS_CLI_PROFILE, or default if it is unset. login, logout, and status also take --profile to name one directly. Profile names can use letters, numbers, hyphens, and underscores.

Running login again on an existing profile only replaces what the wizard asks about; other saved settings are kept.

.env Files

Everything login stores can also come from environment variables, or from a .env file in the folder you run canvas-cli from. That suits shared machines and scripts, where you would rather not store anything:

CANVAS_BASE_URL=https://school.instructure.com/api/v1
CANVAS_ACCESS_TOKEN=12345~abcdef...
AI_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...

Keep .env out of version control. A real environment variable always wins over the same one in .env.

Variables

Precedence

When the same setting comes from more than one place, the first of these wins:

1. An environment variable set in your shell
2. The same variable in .env in the current folder
3. What canvas-cli login or /model stored for the active profile

Each setting is resolved on its own. If you set AI_PROVIDER in the environment to something other than your saved provider, set AI_MODEL too, or the saved model is sent to the new provider. And because /model saves to config.json, a variable in your shell or .env overrides it the next time you start canvas-cli.

canvas-cli status shows the Canvas address, whether a token is set, and where it is stored, without contacting Canvas. Its AI line shows the provider saved in config.json, even when AI_PROVIDER overrides it. /doctor in the shell checks what is actually in effect, and whether it works.

config.json

Each profile’s settings are a small JSON file: config.json for the default profile, config.<profile>.json for others. login and /model write it, and you can edit it by hand. Running login again rewrites the whole file, so set ingestSubmissionFeedback again afterwards if you had changed it.

{
	"canvasBaseUrl": "https://school.instructure.com",
	"aiProvider": "anthropic",
	"aiModel": "claude-opus-5",
	"aiEffort": "high",
	"ingestSubmissionFeedback": true
}