Metadata-Version: 2.5
Name: canvas
Version: 1.3.0
Summary: SDK to customize event-driven actions in your Canvas instance
Author-email: Canvas Team <engineering@canvasmedical.com>
License-Expression: MIT
Requires-Python: <3.15,>=3.11
Requires-Dist: anthropic<2,>=1.0.0
Requires-Dist: certifi>=2026.10.23
Requires-Dist: cookiecutter
Requires-Dist: cron-converter<2,>=1.2.1
Requires-Dist: cryptography>=45.0.5
Requires-Dist: defusedxml>=0.7.1
Requires-Dist: deprecation<3,>=2.1.0
Requires-Dist: django-stubs[compatible-mypy]<6,>=5.1.1
Requires-Dist: django-timezone-utils<0.16,>=0.15.0
Requires-Dist: django<6,>=5.1.1
Requires-Dist: env-tools<3,>=2.4.0
Requires-Dist: factory-boy>=3.3.3
Requires-Dist: frozendict>=2.4.6
Requires-Dist: grpcio<2,>=1.78.0
Requires-Dist: ipython<9,>=8.21.0
Requires-Dist: jsonschema<5,>=4.21.1
Requires-Dist: nh3<0.4,>=0.3.0
Requires-Dist: packaging>=24.2
Requires-Dist: pathspec>=0.12.1
Requires-Dist: protobuf<7,>=6
Requires-Dist: psutil<8,>=7.2.2
Requires-Dist: psycopg[binary,pool]<4,>=3.3.3
Requires-Dist: pydantic<3,>=2.12.5
Requires-Dist: pyjwt<3,>=2.15.0
Requires-Dist: python-dotenv<2,>=1.0.1
Requires-Dist: python-logstash-async>=4.0.2
Requires-Dist: rapidfuzz<4,>=3.10.1
Requires-Dist: redis<6,>=5.0.4
Requires-Dist: requests
Requires-Dist: restrictedpython<9,>=8.5
Requires-Dist: sentry-sdk>=2.33.2
Requires-Dist: snowflake-connector-python<5,>=4.7.2
Requires-Dist: statsd<5,>=4.0.1
Requires-Dist: stripe>=14.1.0
Requires-Dist: typer<0.26,>=0.19.2
Requires-Dist: typing-extensions<5,>=4.14.1
Requires-Dist: websocket-client<2,>=1.7.0
Provides-Extra: test-utils
Requires-Dist: pytest-canvas>=0.2.0; extra == 'test-utils'
Description-Content-Type: text/markdown

[![codecov](https://codecov.io/gh/canvas-medical/canvas-plugins/graph/badge.svg?token=P8JJUOJ8FH)](https://codecov.io/gh/canvas-medical/canvas-plugins)

### Getting Started

`pip install canvas`

### Authentication

The CLI authenticates in two ways, and which one a command uses depends on where it sends the request:

| | Canvas Platform sign-in | Instance API credentials |
| --- | --- | --- |
| Set up with | `canvas login`, in your browser, or a [service account token](#service-accounts-for-cicd) in `CANVAS_PLATFORM_TOKEN` | `~/.canvas/credentials.ini`, written by hand |
| Signs in as | you, as a member of your Canvas Platform organizations, or a service account of one organization | an OAuth client (`client_id` / `client_secret`) registered on one instance |
| Reaches | every instance your organizations can deploy to | the instance named by each section of the file |
| Stored in | `~/.canvas/platform-credentials.json`, or the `CANVAS_PLATFORM_TOKEN` environment variable | `credentials.ini`, with instance tokens cached in `~/.canvas/tokens.json` |
| Used by | `login`, `logout`, `init`, `deploy`, `clone`, and while you are signed in `list`, `logs`, `namespace`, `enable` / `disable` / `config list` / `config set` / `config unset` / `uninstall` for every Canvas instance and plugin (one Canvas Platform does not manage is refused) | `install`, and while you are signed out or for localhost `list`, `logs`, `namespace`, `enable` / `disable` / `config list` / `config set` / `config unset` / `uninstall`, each printing a deprecation notice |

A machine can hold both at once, and the CLI picks per command and per plugin as described in [Which plugins go through Canvas Platform](#which-plugins-go-through-canvas-platform), and per instance for `list`, `logs` and `namespace` as described in [Which instances go through Canvas Platform](#which-instances-go-through-canvas-platform).

#### Migrating from `credentials.ini` to Canvas Platform

See [Upgrading to Canvas Platform](https://docs.canvasmedical.com/guides/upgrading-to-canvas-platform/).

#### Instance API credentials

Create a file `~/.canvas/credentials.ini` and add the client_id and client_secret credentials for each of your Canvas instances. 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.

**Example:**

```
[my-canvas-instance]
client_id=myclientid
client_secret=myclientsecret

[my-dev-canvas-instance]
client_id=devclientid
client_secret=devclientsecret
is_default=true

[localhost]
client_id=localclientid
client_secret=localclientsecret
```

### Canvas Platform

Canvas Platform hosts a plugin's git repository and deploys it to the instances it manages. Sign in once per machine with `canvas login`, which opens your browser; the session is stored per platform in `~/.canvas/platform-credentials.json`, readable only by you, and refreshes itself. `canvas login --platform <url>` or `CANVAS_PLATFORM_URL` points the CLI at a platform other than https://platform.canvasmedical.com, and later commands keep using the platform you last signed in to.

A plugin deployed through Canvas Platform has a plain package name (lowercase letters, digits and underscores, starting with a letter, at most 255 characters), used for the manifest `name`, the package folder and its imports. `canvas deploy` also deploys a plugin under a name outside that rule when Canvas Platform holds a plugin of exactly that name you can see, as it does for legacy plugins registered under the names they run as on instances; it deploys under that plugin's publisher, and Platform decides whether you may push and deploy it. `canvas init` recommends the convention `<org prefix>__<package>` (for example `acme__intake`), and `canvas login` lists the prefix of each organization you belong to. The organization that publishes the plugin is the manifest `publisher` (an organization slug), else your organization whose prefix the name carries, else the only organization you can publish in, else the one you pick at a terminal, which a regular `canvas deploy` push records in the manifest. Every deployment names the publisher it settled on.

#### Which plugins go through Canvas Platform

`canvas enable`, `canvas disable`, `canvas config list`, `canvas config set`, `canvas config unset` and `canvas uninstall` work for plugins Canvas Platform manages and for plugins installed straight onto an instance, and each decides per plugin:

- Signed out, the command goes straight to the instance with `credentials.ini`, as `canvas install` always has, and prints a deprecation notice on stderr.
- Signed in, the CLI asks platform for the plugin when a target is a Canvas instance or when no `--instance` or `--host` is given, and the command goes through platform when platform has it, naming the plugin's publisher. A plugin counts only when one of your organizations publishes it or its name carries its publisher's prefix, since an instance can hold a plugin of that name installed with `canvas install` while another organization publishes one on platform, and platform does not tie a prefix to a publisher. For a Canvas employee every plugin platform has counts, and platform's own permission check decides which commands go through: enable, disable and config do, and uninstall needs a role in the customer's organization. Any other plugin is refused with the way to sign out (`canvas logout`, or unsetting `CANVAS_PLATFORM_TOKEN`), unless every target is `localhost` or another host that is not a Canvas instance, which keeps `credentials.ini`. When `--instance` or `--host` names only such hosts, platform is not asked.

`--host` names an instance for a plugin platform does not manage, and is refused for one it does. When an instance refuses `canvas install` because platform manages that plugin, the message names `canvas deploy`.

#### Which instances go through Canvas Platform

`canvas list`, `canvas namespace list` / `inspect` / `reset` / `drop` and `canvas logs` decide per instance:

- Signed in, a Canvas instance in your list and managed by Canvas Platform goes through platform. Any other Canvas instance is refused with the way to sign out (`canvas logout`, or unsetting `CANVAS_PLATFORM_TOKEN`).
- Signed out, or for `localhost` and other hosts that are not Canvas instances, the command uses `credentials.ini` and prints a deprecation notice on stderr.
- A refusal from platform on a managed instance is shown as platform wrote it and is not retried with `credentials.ini`.

`canvas list` shows platform's last inventory of the instance, with when it was collected on stderr, so it can be hours behind the instance; before platform has read the instance at all, the command says so and exits 1. To read the instance itself, sign out with `canvas logout` (or unset `CANVAS_PLATFORM_TOKEN`) and use `credentials.ini`.

git signs in to platform's git server through `canvas git-credential`, a hidden command `canvas deploy`, `canvas init` and `canvas clone` register as the repository's credential helper. It mints a one-hour git token for the plugin and publisher named in the repository path, and the repository's configuration keeps any other credential helper, such as macOS's keychain, from answering for that server.

```console
$ canvas login
$ canvas init                                   # scaffolds acme__my_cool_plugin and registers it
$ canvas deploy my-cool-plugin/acme__my_cool_plugin --instance acme-staging
$ canvas config set acme__my_cool_plugin API_URL=https://api.example.com --instance acme-staging
```

#### Service accounts for CI/CD

A CI/CD pipeline (GitHub Actions, GitLab CI, and the like) signs in to Canvas Platform as a service account, an identity that belongs to an organization rather than to a person, so the pipeline keeps working when whoever set it up leaves, and Platform's audit log names the account behind each push and deploy. An organization admin, plugin developer or deploy manager creates one on the Credentials page in Canvas Platform. A service account can hold the plugin developer and deploy manager roles, and never more than its creator holds. Its token is shown once and is valid for a year.

Store the token as a CI secret and expose it to the job as `CANVAS_PLATFORM_TOKEN`; no `canvas login` is needed:

```yaml
- run: pip install canvas
- run: canvas deploy my-plugin/acme__my_plugin --instance acme-staging --yes
  env:
    CANVAS_PLATFORM_TOKEN: ${{ secrets.CANVAS_PLATFORM_TOKEN }}
```

- When `CANVAS_PLATFORM_TOKEN` is set, every command uses it in place of a `canvas login` session, including the git pushes `canvas deploy` makes, and it takes precedence over a session already stored on the machine.
- The token does not refresh. Rotating or revoking the service account on the Credentials page ends it, and the CLI's next request says so. `canvas logout` does not touch it.
- `--yes` commits uncommitted changes without prompting. A deployment that needs consent for another plugin's custom data exits non-zero and lists the requests, since only a person at a terminal answers those.
- `CANVAS_PLATFORM_URL` points the job at a platform other than https://platform.canvasmedical.com.

#### Deploying from a monorepo

A plugin inside a larger repository deploys with `--snapshot`, which works from any depth in that repository and leaves its `origin`, config and index alone:

```console
$ canvas deploy plugins/acme__intake --snapshot --instance acme-staging
```

- The package folder as committed at HEAD becomes one new commit on the plugin's `main` in Canvas Platform. Files on `main` beside the package folder are kept, and an unchanged package pushes nothing.
- The commit is authored as the signed-in person or service account, and carries `Monorepo-Commit` and `Monorepo-Path` trailers naming its source.
- Uncommitted changes in the package are refused, even with `--yes`. So are submodules, symbolic links and files stored through a filter such as Git LFS or git-crypt, which would not reach an instance as their content.
- Deploy refuses when HEAD lacks changes to the package that the commit `main` was last deployed from made, which would roll the plugin back, and names the files. A branch that was deployed and then squash- or rebase-merged passes, since HEAD carries its changes.
- A commit on `main`'s first-parent history tagged `snapshot-baseline/<anything>`, as Canvas Studio tags the commit it starts `main` from, counts as a snapshot, and deploy starts from the newest snapshot; lightweight and annotated tags both count. A tagged commit without a `Monorepo-Commit` trailer has nothing to roll back. To mark one by hand, push the tag from a `canvas clone` checkout (`git tag snapshot-baseline/<sha> <sha>`, then `git push origin snapshot-baseline/<sha>`).
- Deploy refuses when `main` has changes to the package since the last snapshot, such as a catalog listing edited in Canvas Platform, that the snapshot would replace. At a terminal it asks before replacing them.
- Deploy warns when HEAD is on no remote branch, since that code has not been through the repository's review.
- With `--branch`, the snapshot goes to that branch, built on its tip on Canvas Platform when it exists and otherwise on `main`, and an unchanged package points a new branch at `main`'s commit. The checks against edits made in Canvas Platform and against rolling back read the branch when it exists, so a snapshot from a checkout lacking what the branch was last deployed from is refused, and read `main` for a new branch.
- The manifest `name` decides which Platform repository a snapshot goes to, so deploys from any checkout or CI job land on the same `main`. The CI job needs no git identity.
- The rollback check needs the commit `main` was last deployed from, which a shallow checkout usually lacks, so deploy skips the check there and says so on stderr. Check out full history without file contents to keep it, for example `fetch-depth: 0` with `filter: blob:none` in `actions/checkout`.

**Usage**:

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

**Options**:

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

**Commands**:

- `login`: Sign in to Canvas Platform through your browser
- `logout`: Sign out of Canvas Platform
- `whoami`: Show which Canvas Platform you are signed in to, and as whom
- `init`: Create a new plugin
- `deploy`: Publish a plugin to Canvas Platform and deploy it
- `clone`: Clone a plugin's repository from Canvas Platform
- `install`: Install a plugin into a Canvas instance
- `uninstall`: Uninstall a plugin
- `config`: List, set and clear plugin variables
- `disable`: Disable a plugin from a Canvas instance
- `enable`: Enable 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 login`

Sign in to Canvas Platform through your browser (OAuth authorization code with PKCE). The sign-in URL is also printed, for a machine without a browser.

**Usage**:

```console
$ canvas login [OPTIONS]
```

**Options**:

- `--platform TEXT`: Canvas Platform URL
- `--help`: Show this message and exit.

## `canvas logout`

Revoke this machine's Canvas Platform session and delete its stored tokens. A service account token in `CANVAS_PLATFORM_TOKEN` is left alone, and the command says that commands still act as that account.

**Usage**:

```console
$ canvas logout [OPTIONS]
```

**Options**:

- `--platform TEXT`: Canvas Platform URL
- `--help`: Show this message and exit.

## `canvas whoami`

Show the platform the CLI uses and where that choice came from (`--platform`, `CANVAS_PLATFORM_URL`, your last `canvas login`, or the default), then the account it signs in as, whether the credential is a `canvas login` session or `CANVAS_PLATFORM_TOKEN`, and each organization's plugin prefix and what you can do there. It asks platform, so a revoked or expired credential is reported rather than shown as signed in. No token is printed. Exits non-zero when not signed in.

**Usage**:

```console
$ canvas whoami [OPTIONS]
```

**Options**:

- `--platform TEXT`: Canvas Platform URL
- `--help`: Show this message and exit.

## `canvas init`

Create a new plugin. Signed in to Canvas Platform, the package is named `<org prefix>__<package>` by convention, its manifest records the `publisher`, and it is registered with platform and given a git repository whose `origin` is platform. Signed out, it is named from the project name alone and scaffolded without registration or a git repository, and `init` says that `canvas login` then `canvas init` gives a registered plugin.

**Usage**:

```console
$ canvas init [OPTIONS] [PLUGIN_TYPE]
```

**Arguments**:

- `PLUGIN_TYPE`: `handler` (default) or `application`

**Options**:

- `--org TEXT`: Organization that publishes the plugin, when you can publish in several
- `--help`: Show this message and exit.

## `canvas deploy`

Publish a plugin's code to Canvas Platform and deploy it. The manifest `name` is a plain package name, and the package folder must have the same name, which deploy checks before committing or pushing. The publisher is the manifest `publisher`, else your organization whose prefix the name carries, else the only organization you can publish in, else, at a terminal, the organization you pick, which a regular push writes into the manifest after checking the package, so the push commits it (with `--ref`, `--no-push` or `--snapshot` it prints the line to add instead); without a terminal, several organizations are refused with the manifest line that chooses one. Deploy registers the plugin, points the repository's `origin` at platform with a credential helper, commits uncommitted changes after you confirm, pushes HEAD to `main`, deploys that commit and waits for each target's outcome. Consent requests for cross-plugin custom data access are answered inline at a terminal; under `--yes` or without a terminal, deploy lists them with the deployment id and exits non-zero without answering them. The repository is rooted at the directory containing the package. Without a terminal to confirm at, uncommitted changes are refused rather than committed unless `--yes` is passed.

**Usage**:

```console
$ canvas deploy [OPTIONS] PLUGIN_DIR
$ canvas deploy --plugin [PUBLISHER/]NAME@VERSION [--plugin ...] [OPTIONS]
```

**Arguments**:

- `PLUGIN_DIR`: Path to the plugin package. Omitted with `--plugin`

**Options**:

- `--plugin TEXT`: Deploy a released plugin, written `[<publisher>/]<name>@<version>` with an exact version in its normal form, without a plugin folder or a push. Repeatable; every `--plugin` goes out in one deployment. Without a publisher, Canvas Platform finds the plugin by name. Takes no `PLUGIN_DIR`, `--ref`, `--no-push`, `--push-only`, `--snapshot` or `--branch`. See [Dependencies and bundles](#dependencies-and-bundles)
- `--instance TEXT`: Instance to deploy to, repeatable. Without it, deploy targets the only instance you can deploy to and otherwise lists the choices
- `--ref TEXT`: Deploy a pushed branch, tag or commit as-is, without pushing
- `--no-push`: Deploy the pushed `main` as-is, without pushing
- `--push-only`: Push HEAD to `main`, or to the `--branch` branch, without deploying it to any instance, so the plugin's code and its catalog listing are updated on Canvas Platform and no instance is needed. Takes no `--instance`, `--ref` or `--no-push`
- `--branch TEXT`: Push HEAD to this branch on Canvas Platform instead of `main`, and deploy that commit. Platform deploys a commit not on `main` only to your organization's test instances, and refuses other instances with a message naming them. Works with `--push-only` and `--snapshot`. Takes no `--ref` or `--no-push`, and refuses `main` and the plugin's default branch
- `--snapshot`: Push the committed contents of a plugin inside a larger repository, such as a monorepo, as one new commit on `main`, or on the `--branch` branch, leaving that repository's remotes alone. See [Deploying from a monorepo](#deploying-from-a-monorepo). Takes no `--ref` or `--no-push`
- `-y, --yes`: Commit uncommitted changes without prompting, with the default message. Does not approve consent requests: a deployment that needs consent exits non-zero and lists them
- `--help`: Show this message and exit.

### Dependencies and bundles

A manifest's `dependencies` name plugins that Canvas Platform installs with it. Each entry has exactly three keys, all required: `name`, `publisher` (the slug of the organization that publishes it), and `version`, a pin in one of two forms. A plugin with `"bundle": true` is made only of its dependencies and its catalog listing, carries no `components`, `custom_data`, `variables` or `secrets`, and `canvas install` refuses one.

```json
"dependencies": [
  {"name": "scribe_core", "publisher": "canvas-medical", "version": "1.16.0"},
  {"name": "commands_kit", "publisher": "canvas-medical", "version": "~=0.1.1"}
]
```

- An exact PEP 440 version in its normal form, such as `1.16.0`, installs that version. A version written another way, such as `v1.16.0`, is refused with its normal form as the suggestion.
- A compatible release, `~=` followed by at least two version components, accepts any version in its range: `~=1.16` is 1.16 or later below 2.0, and `~=0.1.1` is 0.1.1 or later below 0.2. Other specifiers (`>=`, `<`, `==`, `!=`, `===`, comma-separated sets, wildcards, `~=1`) are refused.
- A plugin cannot depend on itself (its own name, with no `publisher` in its manifest or the same one), and a dependency's name and publisher appear once.
- Each dependency must already be on Canvas Platform at a version its pin accepts. Its publisher pushes each release on its own, outside any bundle, with `canvas deploy <plugin> --push-only --snapshot`, which updates the plugin's code and catalog listing without deploying it anywhere.
- Deploying a plugin or bundle with `dependencies` works like any other deploy: the CLI pushes the plugin and creates one deployment naming it, and Canvas Platform resolves the dependencies and installs them in order. Each target's `wave` is shown when platform reports it.

Versions follow semantic versioning: a compatible pin moves within one major version, and a release that changes the major version is one no existing compatible pin reaches. When two plugins share a dependency, such as two products built on the same core plugin, moving that dependency to a new major means every plugin pinning it moves to a release pinning the new major in the same deployment. `canvas deploy --plugin` does that without a plugin folder or a push, deploying released versions of several plugins in one deployment:

```console
$ canvas deploy --plugin canvas-medical/scribe@2.0.0 --plugin acme/intake@3.0.0 --instance acme-staging
```

Each `--plugin` names an exact version, which Canvas Platform resolves to the newest revision on `main` carrying it. When a deployment would leave installed plugins disagreeing about a dependency, Canvas Platform refuses it with a sentence naming the plugins. When each plugin in the way has a release that fits, the sentence ends with the `canvas deploy --plugin ...` command that moves them together, and `canvas deploy` prints it as an error. For a deploy of one plugin, at a terminal and without `--yes`, it then asks whether to deploy them together and, on yes, resends the deployment as it was, the plugin at the ref or version it named, with the plugins in the way added at their releases, and names everything it deploys. Under `--yes`, without a terminal, or for a deploy naming several `--plugin`, it deploys nothing.

## `canvas clone`

Clone a plugin's repository from Canvas Platform with `origin` and the credential helper set, ready for `canvas deploy`.

**Usage**:

```console
$ canvas clone [OPTIONS] NAME [DIRECTORY]
```

**Arguments**:

- `NAME`: Plugin name, e.g. `intake` [required]
- `DIRECTORY`: Where to clone it, a directory named after the plugin by default

**Options**:

- `--publisher <slug>`: Organization that publishes the plugin, when two publishers share the name
- `--help`: Show this message and exit.

## `canvas install`

Install a plugin into a Canvas instance.

**Usage**:

```console
$ 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.

## `canvas uninstall`

Uninstall a plugin. A plugin Canvas Platform manages is removed by an uninstall deployment from each `--instance`, which is required. Any other plugin is removed from the instance directly.

**Usage**:

```console
$ canvas uninstall [OPTIONS] NAME
```

**Arguments**:

- `NAME`: Plugin name to uninstall [required]

**Options**:

- `--instance TEXT`: Instance to uninstall from, repeatable
- `--host TEXT`: Canvas instance to connect to, for a plugin Canvas Platform does not manage
- `--force`: Uninstall an enabled plugin from an instance directly
- `--help`: Show this message and exit.

## `canvas config list`

List a plugin's variables and whether each is set; values are never shown. For a plugin Canvas Platform manages, the keys come from platform, and without `--instance` the only instance it is installed on is used. For any other plugin, they are read from the instance directly.

**Usage**:

```console
$ canvas config list [OPTIONS] PLUGIN_NAME
```

**Arguments**:

- `PLUGIN_NAME`: Plugin name to list variables for [required]

**Options**:

- `--instance TEXT`: Instance to read from, repeatable
- `--host TEXT`: Canvas instance to connect to, for a plugin Canvas Platform does not manage
- `--help`: Show this message and exit.

## `canvas config set` / `canvas config unset`

Set or clear a plugin's variable values. For a plugin Canvas Platform manages, values are stored in platform and a configure deployment brings them to the running plugin; without `--instance`, the only instance it is installed on that you can configure is targeted. A variable's sensitivity comes from the manifest's `variables`, and `--secret` / `--variable` state it for a key no revision declares. For any other plugin, values are written to the instance directly, and `unset` sets them empty.

**Usage**:

```console
$ canvas config set [OPTIONS] PLUGIN_NAME [KEY=VALUE]...
$ canvas config unset [OPTIONS] PLUGIN_NAME KEY...
```

**Options**:

- `--instance TEXT`: Instance to configure, repeatable
- `--host TEXT`: Canvas instance to connect to, for a plugin Canvas Platform does not manage
- `--secret KEY=VALUE`, `--variable KEY=VALUE`: (`set` only) a sensitive or non-sensitive value for an undeclared key
- `--help`: Show this message and exit.

## `canvas enable`

Enable a plugin. For a plugin Canvas Platform manages, an enable deployment switches it on at each `--instance`; without `--instance`, the only instance it is installed on that you can deploy to is targeted. For any other plugin, it is enabled on the instance directly.

**Usage**:

```console
$ canvas enable [OPTIONS] PLUGIN_NAME
```

**Arguments**:

- `PLUGIN_NAME`: Plugin name to enable [required]

**Options**:

- `--instance TEXT`: Instance to enable it on, repeatable
- `--host TEXT`: Canvas instance to connect to, for a plugin Canvas Platform does not manage
- `--help`: Show this message and exit.

## `canvas disable`

Disable a plugin. For a plugin Canvas Platform manages, a disable deployment switches it off at each `--instance`; without `--instance`, the only instance it is installed on that you can deploy to is targeted. For any other plugin, it is disabled on the instance directly.

**Usage**:

```console
$ canvas disable [OPTIONS] PLUGIN_NAME
```

**Arguments**:

- `PLUGIN_NAME`: Plugin name to disable [required]

**Options**:

- `--instance TEXT`: Instance to disable it on, repeatable
- `--host TEXT`: Canvas instance to connect to, for a plugin Canvas Platform does not manage
- `--help`: Show this message and exit.

## `canvas list`

List all plugins from a Canvas instance. For an instance Canvas Platform manages, the list is platform's last inventory of it.

**Usage**:

```console
$ 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**:

```console
$ canvas validate-manifest [OPTIONS] PACKAGE
```

**Arguments**:

- `PLUGIN_NAME`: Path to plugin to install [required]

**Options**:

- `--help`: Show this message and exit.

## `canvas logs`

Listens and prints log streams from the instance.

- Signed in to Canvas Platform, `canvas logs` asks Platform for a 15-minute log token for an instance it manages. An instance Platform does not manage is refused with the way to sign out (`canvas logout`, or unsetting `CANVAS_PLATFORM_TOKEN`), so `credentials.ini` is used only once you are signed out.
- While following, Console closes the stream with code 4401 once the log token is inactive; `canvas logs` then asks Platform for a fresh token, which re-checks your access, and reconnects.
- Signed out, or for localhost and other hosts that are not Canvas instances, `canvas logs` uses `credentials.ini` and prints a deprecation notice on stderr.
- `--plugin` filters the live stream as well as history, by the plugin each line is tagged with: the plugin runner's handler lines and the effect failures Canvas logs for that plugin. Like history, it leaves out untagged lines, such as plugin load and install.

**Usage**:

```console
$ canvas logs [OPTIONS]
```

**Options**:

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