CLI reference

Install: npm install -g @canvasmesh/cli. The binary is canvasmesh.

All commands except download require canvasmesh login first.

Global options

Flag	Description
--debug	Print all log entries to stderr in real time
--version	Show CLI version
--help	Show help for any command

Debug mode is useful for diagnosing slow requests or authentication issues:

canvasmesh --debug push image.png

Logging

Every command and API request is logged to ~/.canvasmesh/cli.log with timestamps, duration in milliseconds, and structured metadata. The log file is created automatically on first use.

Example log entries:

2026-04-22T05:10:00.000Z [DEBUG] POST /v1/upload/presign {"status":200,"ms":120}
2026-04-22T05:10:00.342Z [INFO] push {"canvas_id":"01H...","file":"demo.png","ext":"png","size":84210,"permanent":false}
2026-04-22T05:10:00.345Z [INFO] command push completed {"ms":892}

login

Save API key and endpoint to ~/.canvasmesh/config.json.

# Interactive mode — prompts for API key and endpoint
canvasmesh login

# Non-interactive mode
canvasmesh login --token <api-key> [--endpoint <url>] [--web-url <url>]

When called without --token, the CLI enters interactive mode and prompts for each value with sensible defaults:

$ canvasmesh login
CanvasMesh Login
Create an API key in the Settings page of the web dashboard.

API Key: sk-xxxx
API Endpoint (https://api.canvasmesh.app):
✓ API key saved (endpoint: https://api.canvasmesh.app)

Flag	Required	Default	Description
--token	no	—	API key from canvasmesh.app Settings. Omit to enter interactive mode
--endpoint	no	https://api.canvasmesh.app	API base URL
--web-url	no	https://canvasmesh.app	Web dashboard URL (used by view)

logout

Remove the stored API key.

canvasmesh logout

config

View or update local configuration.

# Show current config
canvasmesh config show

# Set a value
canvasmesh config set <key> <value>

Allowed keys: endpoint, web_url.

whoami

Show the authenticated user and workspace.

canvasmesh whoami

usage

Display workspace storage statistics.

canvasmesh usage [--json]

Flag	Default	Description
--json	(off)	Emit raw JSON

push

Upload a file and create a new canvas (temporary 24h by default).

canvasmesh push <file> [--title <title>] [--save]

Flag	Default	Description
--title	filename	Human-readable canvas title
--save	(off)	Save permanently (no 24h expiry)

pull

Download a canvas’s raw content.

canvasmesh pull <canvas-id> [--output <path>]

Flag	Default	Description
--output	stdout	Write file to this path

list

List canvases in the current workspace.

canvasmesh list [--type <type>] [--limit <n>] [--json]

Flag	Default	Description
--type	(all)	Filter by file type (e.g. png, pdf, html)
--limit	20	Maximum number of results
--json	(off)	Emit JSON instead of a table

share

Create a public share link.

canvasmesh share <canvas-id> [--expires <duration>]

--expires accepts duration strings: 30m, 24h, 7d. Omit for a link that never expires.

view

Open a canvas in the default browser.

canvasmesh view <canvas-id>

Supports macOS, Windows, and Linux (xdg-open).

download

Download a file from a public share link. Requires authentication.

canvasmesh download <share-url-or-token> [--output <path>] [--info]

Flag	Default	Description
--output	<title>.<ext>	Output file path
--info	(off)	Print canvas metadata as JSON without downloading

Environment variables

Variable	Description
CANVAS_API_KEY	Overrides stored token
CANVAS_ENDPOINT	Overrides stored endpoint
CANVAS_WEB_URL	Overrides stored web URL

Environment variables take precedence over ~/.canvasmesh/config.json.

Files

Path	Description
~/.canvasmesh/config.json	Credentials and endpoint configuration
~/.canvasmesh/cli.log	Command and API request log with timing

Exit codes

Code	Meaning
0	Success
1	Generic error