Canvas CLI

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

Usage:

$ canvas logs [OPTIONS]

Options:

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

canvas config list #

List all secrets from a plugin.

Usage:

$ canvas config list [OPTIONS] PLUGIN

Arguments:

  • PLUGIN: Plugin name to list secrets for

Options:

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

canvas config set #

Configure plugin secrets.

Usage:

$ canvas config set [OPTIONS] PLUGIN

Arguments:

  • PLUGIN: Plugin name to list secrets for
  • SECRETS...: Secrets to set, e.g. Key=value

Options:

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