# @canvas-js/cli > Canvas provides a command line interface for running applications in Node.js, that join the peer-to-peer network. Latest version **0.16.1** (published 2025-07-30) · 0 weekly downloads ## Install ```sh npm install @canvas-js/cli pnpm add @canvas-js/cli yarn add @canvas-js/cli bun add @canvas-js/cli ``` Provides the command `canvas`. ## Health **Score 35/100 (D)** — status: maintenance-mode. Positive: has types; esm support; no vulnerabilities. Warnings: low downloads; pre 1.0. Negative: stale; low maintenance score. ## Facts | | | |---|---| | Version | 0.16.1 | | Published | 2025-07-30 | | First published | 2022-05-16 | | Weekly downloads | 0 | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Dependencies | 32 | | Unpacked size | 111.8 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Author | Canvas Technologies, Inc. | | Maintainers | joelg, raykyri, rjwebb | ## Links - npm: https://www.npmjs.com/package/@canvas-js/cli - npm.io page: https://npm.io/package/@canvas-js/cli ## Dependencies (32) - [ws](https://npm.io/package/ws.md) ^8.18.2 - [cors](https://npm.io/package/cors.md) ^2.8.5 - [siwe](https://npm.io/package/siwe.md) ^3.0.0 - [chalk](https://npm.io/package/chalk.md) ^5.4.1 - [yargs](https://npm.io/package/yargs.md) ^17.7.2 - [dotenv](https://npm.io/package/dotenv.md) ^16.4.7 - [ethers](https://npm.io/package/ethers.md) ^6.13.5 - [express](https://npm.io/package/express.md) ^5.1.0 - [p-queue](https://npm.io/package/p-queue.md) ^8.1.0 - [pkg-dir](https://npm.io/package/pkg-dir.md) ^8.0.0 - [prompts](https://npm.io/package/prompts.md) ^2.4.2 - [@types/ws](https://npm.io/package/@types/ws.md) ^8.5.14 - [stoppable](https://npm.io/package/stoppable.md) ^1.1.0 - [prom-client](https://npm.io/package/prom-client.md) ^15.1.2 - [multiformats](https://npm.io/package/multiformats.md) ^13.3.7 - [@noble/hashes](https://npm.io/package/@noble/hashes.md) ^1.8.0 - [@ipld/dag-cbor](https://npm.io/package/@ipld/dag-cbor.md) ^9.2.4 - [@ipld/dag-json](https://npm.io/package/@ipld/dag-json.md) ^10.2.5 - [@canvas-js/core](https://npm.io/package/@canvas-js/core.md) 0.16.1 - [@libp2p/peer-id](https://npm.io/package/@libp2p/peer-id.md) ^5.1.6 - [@types/websocket](https://npm.io/package/@types/websocket.md) ^1.0.10 - [http-status-codes](https://npm.io/package/http-status-codes.md) ^2.3.0 - [@canvas-js/gossiplog](https://npm.io/package/@canvas-js/gossiplog.md) 0.16.1 - [@canvas-js/interfaces](https://npm.io/package/@canvas-js/interfaces.md) 0.16.1 - [@canvas-js/signer-atp](https://npm.io/package/@canvas-js/signer-atp.md) 0.16.1 - [@multiformats/multiaddr](https://npm.io/package/@multiformats/multiaddr.md) ^12.4.1 - [@canvas-js/signer-cosmos](https://npm.io/package/@canvas-js/signer-cosmos.md) 0.16.1 - [@canvas-js/signer-solana](https://npm.io/package/@canvas-js/signer-solana.md) 0.16.1 - [@canvas-js/signer-ethereum](https://npm.io/package/@canvas-js/signer-ethereum.md) 0.16.1 - [@canvas-js/network-explorer](https://npm.io/package/@canvas-js/network-explorer.md) 0.16.1 - [@canvas-js/signer-substrate](https://npm.io/package/@canvas-js/signer-substrate.md) 0.16.1 - [@multiformats/multiaddr-matcher](https://npm.io/package/@multiformats/multiaddr-matcher.md) ^1.6.0 ## Recent versions - 0.16.1 (latest) — 2025-07-30 - 0.16.0-next.9 (next) — 2025-07-13 - 0.10.0-beta.3 (beta) — 2024-06-27 - 0.10.0-alpha.1 (alpha) — 2024-05-21 - 0.8.26-main-488c798d (main) — 2024-02-15 - 0.16.0 — 2025-07-08 - 0.16.0-next.8 — 2025-06-26 - 0.16.0-next.7 — 2025-06-25 - 0.16.0-next.6 — 2025-06-25 - 0.16.0-next.5 — 2025-06-18 - 0.16.0-next.4 — 2025-06-18 - 0.16.0-next.3 — 2025-06-13 - 0.16.0-next.2 — 2025-06-13 - 0.16.0-next.1 — 2025-06-13 - 0.16.0-next.0 — 2025-06-13 - … 251 more at https://npm.io/package/@canvas-js/cli/versions ## README # @canvas-js/cli Canvas provides a command line interface for running applications in Node.js, that join the peer-to-peer network. ## Installation To install the CLI, run: ``` npm install -g @canvas-js/cli ``` ## Usage ``` canvas Commands: canvas init Initialize a new application canvas info Show the model schema and action names in a contract canvas run Run a Canvas application canvas export Export the action log as dag-json to stdout canvas import Import an action log from stdin Options: --version Show version number --help Show help ``` ## Running an application The main command is `canvas run `. This will start a libp2p node, SQLite database, QuickJS VM for processing actions, and an HTTP API server. By default, `canvas run contract.ts` will run a contract with ephemeral storage persistence. For persistence, you should provide a data directory like `canvas run data/myapp --init contract.ts` to save the message log and model database to disk. You only need to provide the --init argument the first time when setting up the data directory. Use the `--help` flag to learn more. ### Joining the libp2p mesh In the likely case that your machine is behind a NAT layer, you have to provide the CLI with both an internal port bind a WebSocket server using the `--listen` option, and a public external address using the `--announce` option. Both of these must be formatted as [multiaddrs](https://github.com/multiformats/multiaddr), the generic composable network address format used by libp2p. For example, this tells the CLI to listen on port 4444 and advertise `wss://foobar.com:8000` as the public address: ``` $ canvas run ./myapp --listen /ip4/0.0.0.0/tcp/4444/ws --announce /dns4/foobar.com/tcp/443/wss ``` This assumes that you've configured your server to handle incoming secure websocket connections over TLS on port `443`, do TLS termination, and proxy the connection to your internal port `4444`. A few things to note: - You can pass as many `--announce` addresses as you want, but only one `--listen` address. - You don't have to use TLS, but if you don't, browsers running embedded Canvas apps won't be able to talk to your peer. - If you'd prefer to announce on a public static IP instead of a DNS name, announce on `/ip4/{publicIP}/tcp/{port}/wss`. - If your DNS name has IPv6 `AAAA` records, you can use `/dns6` in addition to `/dns4`. - You can pass a `--listen` address without an `--announce` address to delegate to libp2p's autonat and identify services, which are works in progress. It's best to provide a public address if you have one. Almost always, `--listen` will be of the form `/ip4/0.0.0.0/tcp/${port}/ws`, and `--announce` will be of the form `/dns4/${hostname}/tcp/{port}/wss`. ## HTTP API Running a Canvas app with `canvas run` will serve an HTTP API at `http://127.0.0.1:8000/api/` by default. You can change the port with the `--port` option. The basic routes are: - `GET /api` - get application metadata - `GET /api/models/:model` - get model records - `GET /api/models/:model/:key` - get a model record by primary key - `GET /api/clock` - get the next logical clock value from the log - `GET /api/messages` - query ranges of log messages - `GET /api/messages/:id` - get a message from the log - `POST /api/messages` - apply a signed message - `GET /api/connections` - current libp2p connections - `GET /api/peers` - current libp2p pubsub peers - `POST /api/ping/:peerId` - ping a peer via libp2p ### Exposing optional endpoints Some optional API endpoints are disabled by default, since they should't be exposed publicly. - `--metrics` - serve Prometheus metrics at `/metrics` The metrics reported to Prometheus include default NodeJS metric, internal libp2p metrics, and some additional metrics specific to Canvas `Core`. #### `canvas_sync_time` A histogram of MST sync times. | label name | type | | ---------- | -------- | | `topic` | `string` | | `duration` | `number` | | `peer` | `string` | #### `canvas_messages` A counter of messages applied | label name | type | description | | ---------- | -------- | ------------------------- | | `topic` | `string` | | | `type` | `string` | `"action"` or `"session"` | ## Serving static content alongside the API `--static [directory]` can be used to serve a static directory alongside the application API. This is the easiest way to bundle a frontend that uses Canvas as a backend. If the `--static` flag is provided, the root path `/` serves the files in `[directory]`. ## Serving the network explorer `--network-explorer` serves an explorer for the model database and message log. If you're running the network explorer, you can also provide `--admin ` to set an admin address that can upgrade the currently running contract in the CLI. --- _Source: https://npm.io/package/@canvas-js/cli · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._