Skip to main content

codecov

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 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, and per instance for list, logs and namespace as described in Which instances go through Canvas Platform.

Migrating from credentials.ini to Canvas Platform

See 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 63 characters), used for the manifest name, the package folder and its imports. 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.

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

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

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

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

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

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

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

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

$ canvas deploy [OPTIONS] PLUGIN_DIR

Arguments:

  • PLUGIN_DIR: Path to the plugin package [required]

Options:

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

canvas clone

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

Usage:

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

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

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

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

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

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

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

$ 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] 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.

Usage:

$ canvas logs [OPTIONS]

Options:

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

Metadata

Release files for canvas 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for canvas 1.0.0
File Size Uploaded Provenance Actions
canvas-1.0.0.tar.gz 2.6 MB With provenance Details for canvas-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for canvas 1.0.0
File Interpreter ABI Platform Actions
canvas-1.0.0-py3-none-any.whl Python 3 none any Details for canvas-1.0.0-py3-none-any.whl

Total release size: 5.6 MB

Release files / canvas-1.0.0.tar.gz

Download URL canvas-1.0.0.tar.gz
Size 2.6 MB
Tags Source
SHA-256 checksum
How to use checksums
9132cc78adba3e6f6d330ffb1a73d2eacd2a4f9b22f84d779925ca96063b90e3
BLAKE2b-256 checksum
How to use checksums
e4075d84dc87bda8c55afa75027845e6c7ca746804c9750dc66da8d1e8809143
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Release files / canvas-1.0.0-py3-none-any.whl

Download URL canvas-1.0.0-py3-none-any.whl
Size 3.0 MB
Tags Python 3
SHA-256 checksum
How to use checksums
18314e24071f88143fbf3735ef2f4d0f2a905063c02b8867e8e78774f2e3f9dd
BLAKE2b-256 checksum
How to use checksums
42823f8d1228ccebc79e0069daac2cb2fe661848dd89ec7a6d09eb6fcd2ee295
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Security for canvas 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for canvas-1.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page