Configuration¶

Canvas CLI can be configured to work with multiple Canvas instances and customized for your workflow.

Configuration File¶

Canvas CLI stores configuration in ~/.canvas-cli/config.yaml.

default_instance: production
instances:
  production:
    name: production
    url: https://canvas.example.com
    # OAuth credentials (optional - for auto-refresh)
    client_id: "your-client-id"
    client_secret: "your-client-secret"
  sandbox:
    name: sandbox
    url: https://canvas-sandbox.example.com
    # API token (alternative to OAuth)
    token: "7~your-api-token-here"

Authentication Methods

API Token: Stored directly in config file (set via canvas auth token set)
OAuth tokens: Stored securely in your system keychain (set via canvas auth login)

You can mix both methods - use OAuth for production and API tokens for testing/sandbox environments.

Managing Instances¶

Add an Instance¶

# Add a new instance
canvas config add production --url https://canvas.example.com

# Add with description
canvas config add staging --url https://canvas-staging.example.com --description "Staging environment"

After adding, authenticate with OAuth:

canvas auth login --instance production

Or set an API token:

canvas auth token set production --token 7~your-token-here

List Instances¶

canvas config list

Switch Default Instance¶

canvas config use sandbox

Remove an Instance¶

canvas config remove sandbox

Set a Default Account¶

Set (or auto-detect) the default account ID used when a command needs an account ID and none is given:

# Set manually
canvas config account production 1

# Auto-detect from the API
canvas config account production

Show Current Configuration¶

canvas config show

Environment Variables¶

Canvas CLI supports environment variables for configuration (useful for CI/CD):

Variable	Description
`CANVAS_URL`	Canvas instance URL
`CANVAS_TOKEN`	API access token
`CANVAS_REQUESTS_PER_SEC`	Rate limit (default: 5.0)

Example:

export CANVAS_URL=https://canvas.example.com
export CANVAS_TOKEN=your-api-token
canvas courses list

Priority

Environment variables take precedence over the config file.

See the Environment Variables reference for the full list and details.

Command-Line Overrides¶

You can override configuration with command-line flags:

# Override instance
canvas courses list --instance https://other-canvas.example.com

# Override output format
canvas courses list --output json

# Disable caching
canvas courses list --no-cache

Multiple Instances¶

Canvas CLI supports working with multiple Canvas instances. This is useful for:

Development vs. production environments
Multiple institutions
Testing and staging

Switching Instances¶

# Use a specific instance for one command
canvas courses list --instance sandbox

# Switch default instance
canvas config use sandbox

Syncing Between Instances¶

# Sync course 123 from production to course 456 on sandbox
canvas sync course production 123 sandbox 456

See the Course Sync Tutorial for more details.