CLI Reference
The Checkpoint CLI (checkpoint) tunnels your local dev server and injects the feedback script into every page. Current version: 0.5.0.
Installation
Install a tunnel provider first (cloudflared is recommended — free, no account needed):
checkpoint login
Sign in to your Checkpoint account. Opens the browser for authentication. Detects if already logged in and skips the browser flow if so.
The login flow uses a browser-based callback — no passwords are ever typed into the terminal. Sessions stay valid indefinitely as long as the refresh token is valid.
checkpoint start
Start tunneling a local port and get a shareable link.
| Flag | Required | Description |
|---|---|---|
| -p, --port <port> | required | Local port your dev server is running on (e.g. 3000, 5173) |
| -n, --name <name> | optional | Tunnel name. Prompted interactively if omitted. Reuse a name to resume the same share URL and comments. |
| --provider <provider> | optional | cloudflared (default) or ngrok. Auto-detected from $PATH if not specified. |
What happens step by step
- Checks you are logged in
- Prompts for a tunnel name if
-nwas not passed - Verifies something is actually running on
localhost:<port>(HEAD request, 2s timeout) - Authenticates with Supabase, refreshing tokens if needed
- Auto-detects the tunnel provider from
$PATH(preferscloudflared) - Starts the injection proxy on a random local port
- Launches the tunnel provider pointed at the proxy port
- Registers the tunnel in the database (or reconnects to an existing one with the same name)
- Starts a 30-second heartbeat to keep the tunnel marked
active - Prints the share URL
- Waits until Ctrl+C, then deactivates the tunnel and shuts down cleanly
checkpoint stop
Stop an active tunnel by name. This deactivates the tunnel and marks it as inactive in the dashboard.
| Flag | Required | Description |
|---|---|---|
| -n, --name <name> | required | Name of the tunnel to stop |
checkpoint list
List all tunnels for your workspace with their current status and share URLs.
Reconnecting to existing tunnels
If a tunnel with the same name already exists, the CLI reuses it — updating the connection details — rather than creating a new tunnel. This preserves the share URL and all comments.
This behavior is automatic when you use checkpoint start with a name that already exists. The CLI will:
- Reuse the existing share URL and comments
- Update the tunnel connection details
- Mark the tunnel as active
- Continue the 30-second heartbeat
checkpoint restart
Stop and immediately restart a tunnel. Useful for refreshing the connection or switching providers.
| Flag | Required | Description |
|---|---|---|
| -n, --name <name> | required | Name of the tunnel to restart |
| --provider <provider> | optional | Switch to a different provider (cloudflared or ngrok) |
checkpoint delete
Permanently delete a tunnel and all its comments. This action cannot be undone.
| Flag | Required | Description |
|---|---|---|
| -n, --name <name> | required | Name of the tunnel to delete |
| --force | optional | Skip confirmation prompt (use with caution) |
Common workflows
Starting a new tunnel
Resuming an existing tunnel
Checking tunnel status
Cleaning up old tunnels
checkpoint share
Register an existing public tunnel URL (e.g. from a manually started ngrok session) with Checkpoint without the CLI managing the tunnel process.
| Flag | Required | Description |
|---|---|---|
| -u, --url <url> | required | The public HTTPS tunnel URL to register |
| -n, --name <name> | optional | Name for this tunnel (default: My Tunnel) |
| -p, --port <port> | optional | Local port for reference (default: 3000) |
checkpoint status
Show login status and which tunnel providers are installed. Prints whether you are logged in (and as which email), and which of cloudflared / ngrok are available in $PATH.
checkpoint logout
Sign out and clear saved credentials from this machine. Does not invalidate tokens server-side.
Tunnel providers
| Provider | Detection | Startup timeout | URL pattern |
|---|---|---|---|
| cloudflared | which cloudflared | 30 seconds | *.trycloudflare.com |
| ngrok | which ngrok | 15 seconds | *.ngrok.io / .app / .dev |