Canvas CLI

Last updated: 18 Jul 2025

Getting Started #

Installation #

To install the Canvas CLI, simply pip install canvas. Python 3.11 or 3.12 is required.

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

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

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:

• --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:

• --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.

Usage:

$ canvas logs [OPTIONS]

Options:

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