Canvas CLI

Last updated: 14 May 2026

Getting Started #

Installation using pip #

To install the Canvas CLI using pip, execute pip install canvas. Python 3.11, 3.12, or 3.13 is required.

To upgrade the Canvas CLI if you installed using pip, execute pip install --upgrade canvas.

Installation using uv #

To install the Canvas CLI using uv, execute uv tool install canvas. uv will find or procure an acceptable Python version.

To upgrade the Canvas CLI if you installed using uv, execute uv tool upgrade canvas.

Configuration and Authenticating to Your Canvas Instance #

Create a file ~/.canvas/credentials.ini with sections for each of your Canvas instance subdomains, and add client_id and client_secret credentials to each section. For example, if your Canvas instance url is https://buttered-popcorn.canvasmedical.com/, you would have a section [buttered-popcorn] with key-value pairs for client_id and client_secret.

Example:

[buttered-popcorn]
client_id=butter
client_secret=salt

[dev-buttered-popcorn]
client_id=devbutter
client_secret=devsalt
is_default=true

[localhost]
client_id=localclientid
client_secret=localclientsecret

You can define your default host with is_default=true. If no default is explicitly defined, the Canvas CLI will use the first instance in the file as the default for each of the CLI commands.

You are now ready to use the Canvas CLI

Update Notifications #

The Canvas CLI automatically checks PyPI for newer versions. If an update is available, a notice is printed to standard error after the command output:

[notice] A newer version of canvas is available (0.112.0 → 0.113.0). Upgrade with: pip install --upgrade canvas

• The check runs at most once every 12 hours; the result is cached locally to avoid unnecessary network requests.
• Because the notice is printed to standard error, it will not interfere with piped or redirected command output.
• To disable update checks, set the environment variable CANVAS_NO_UPDATE_CHECK=1.

Usage #

$ canvas [OPTIONS] COMMAND [ARGS]...

Options:

• --version
• --help: Show this message and exit.

Commands #

• init: Create a new plugin
• install: Install a plugin into a Canvas instance
• uninstall: Uninstall a plugin from a Canvas instance
• enable: Enable a plugin from a Canvas instance
• disable: Disable a plugin from a Canvas instance
• list: List all plugins from a Canvas instance
• validate-manifest: Validate the Canvas Manifest json file
• logs: Listen and print log streams from a Canvas instance
• config list: List all secrets from a plugin
• config set: Configure plugin secrets

canvas init #

Create a new plugin.

Usage:

$ canvas init [OPTIONS]

Options:

• --help: Show this message and exit.

canvas install #

Install a plugin into a Canvas instance.

Usage:

$ canvas install [OPTIONS] PLUGIN_NAME

Arguments:

• PLUGIN_NAME: Path to plugin to install [required]

Options:

• --secret TEXT: Secrets to set, e.g. Key=value
• --variable TEXT: Variables to set, e.g. Key=value. Use --variable for non-sensitive configuration and --secret for sensitive values.
• --enable / --disable: Install the plugin in an enabled or disabled state. Defaults to --enable.
• --host TEXT: Canvas instance to connect to
• --help: Show this message and exit.

Notes:

Files can be excluded from the packaged plugin using a .canvasignore in the current working directory. The file behaves similarly to .gitignore

Example

# Exclude test files
test_*.py

canvas uninstall #

Uninstall a plugin from a Canvas instance.

Usage:

$ canvas uninstall [OPTIONS] NAME

Arguments:

• NAME: Plugin name to delete [required]

Options:

• --force: Force uninstallation of the plugin
• --host TEXT: Canvas instance to connect to
• --help: Show this message and exit.

canvas enable #

Enable a plugin from a Canvas instance..

Usage:

$ canvas enable [OPTIONS] NAME

Arguments:

• NAME: Plugin name to enable [required]

Options:

• --host TEXT: Canvas instance to connect to
• --help: Show this message and exit.

canvas disable #

Disable a plugin from a Canvas instance..

Usage:

$ canvas disable [OPTIONS] NAME

Arguments:

• NAME: Plugin name to disable [required]

Options:

• --host TEXT: Canvas instance to connect to
• --help: Show this message and exit.

canvas list #

List all plugins on a Canvas instance.

Usage:

$ canvas list [OPTIONS]

Options:

• --host TEXT: Canvas instance to connect to
• --help: Show this message and exit.

canvas validate-manifest #

Validate the Canvas Manifest json file.

Usage:

$ canvas validate-manifest [OPTIONS] PLUGIN_NAME

Arguments:

• PLUGIN_NAME: Path to plugin to validate [required]

Options:

• --help: Show this message and exit.

canvas logs #

Subscribes to a log stream and prints to your console. Optionally fetches historical logs first.

Usage:

$ canvas logs [OPTIONS]

Options:

• --host TEXT: Canvas instance to connect to
• --help: Show this message and exit.
• --since TEXT: Lookback window (e.g. ‘24h’, ‘2h30m’). Mutually exclusive with –start/–end.
• --start TEXT: Start time (ISO/RFC3339) or ‘now’.
• --end TEXT: End time (ISO/RFC3339) or ‘now’. Defaults to now if start is provided.
• --no-follow: Historical only; do not stream live logs.
• --level TEXT: Repeatable. –level ERROR –level WARN
• --source TEXT: Filter by source/service.
• --page-size INTEGER: Fetch size per page (historical). [default: 200]
• --limit INTEGER: Max historical logs to print.
• --all: Fetch all pages until exhausted (historical).
• --interactive: After each page, prompt to load more.
• --cursor TEXT: Resume token from a previous run.
• --help: Show this message and exit.

canvas config list #

List the variables configured for a plugin. Each variable is rendered as [set] or [not set], with a (sensitive) annotation for sensitive variables. Values themselves are never displayed — to read a value, use the Django Admin UI (gated by managing-user permissions).

Usage:

$ canvas config list [OPTIONS] PLUGIN

Example output:

$ canvas config list my_plugin
  API_TOKEN  [set]  (sensitive)
  LOG_LEVEL  [not set]

Arguments:

• PLUGIN: Plugin name to list variables for

Options:

• --host TEXT: Canvas instance to connect to
• --help: Show this message and exit.

canvas config set #

Set (or update) one or more variables on an installed plugin. Each variable must already be declared in the plugin’s CANVAS_MANIFEST.json. Pass one or more KEY=value pairs as positional arguments.

Usage:

$ canvas config set [OPTIONS] PLUGIN KEY=value [KEY=value ...]

Examples:

Set a single variable:

$ canvas config set my_plugin API_TOKEN=your_api_token_value

Set multiple variables in one call:

$ canvas config set my_plugin API_TOKEN=abc123 LOG_LEVEL=info

Arguments:

• PLUGIN: Plugin name to configure
• KEY=value ...: One or more variables to set

Options:

• --host TEXT: Canvas instance to connect to
• --help: Show this message and exit.

Whether each value is treated as sensitive is determined by the plugin’s CANVAS_MANIFEST.json (variables: [{name, sensitive}]) — canvas config set does not change the sensitive flag.