Skip to content
ZedCloud

The zc CLI

zc does from the terminal what the canvas does in the browser. It’s built for scripts, CI and AI agents: every command has --json output and meaningful exit codes.

Install

Section titled “Install”
Terminal window
curl -fsSL https://raw.githubusercontent.com/BrianPhiri/zc/main/install.sh | sh

Installs to ~/.local/bin without sudo, and checks the download’s SHA-256.

Upgrade by running the installer again, or brew upgrade zc.

Tokens

Section titled “Tokens”

  1. In the dashboard open Profile → Developer and create a token. Pick an expiry (1 to 90 days) and scopes:

    Scope Allows
    read Read workspaces, nodes and plans
    logs:read Read logs
    resources:write Stage new nodes, edits and links
    resources:delete Stage deletions
    deploy Deploy a plan, push code, pull and roll back

  2. Copy it: it’s shown once.

  3. Sign in:

    Terminal window
    zc login --token zcp_...
    zc doctor     # checks the token, scopes, expiry and connection

The token is saved in ~/.config/zc/credentials (or set ZC_TOKEN). A token acts as you and can never do more than your role allows. Revoke it in the same place.

Pick a workspace

Section titled “Pick a workspace”
Terminal window
zc ws list
zc ws use 12          # writes .zc in this folder

Or pass --ws 12, or set ZC_WORKSPACE.

Everyday commands

Section titled “Everyday commands”
Terminal window
zc graph                                  # nodes and links
zc resources create --kind database --subtype postgres --label db
zc link api db                            # stage a link
zc env set api STRIPE_KEY=-               # reads the value from stdin
zc plan                                   # what a deploy would do
zc deploy                                 # ask a person to deploy (prints a review link)
zc deploy --plan-hash 3f9c...             # deploy exactly that plan

All commands

Section titled “All commands”
Command Does
zc login --token T, zc whoami, zc doctor Sign in and check your setup
zc ws list, zc ws use ID List workspaces, set the default
zc graph Show nodes and links
zc resources list / get ID List nodes, or one node’s status, address and diagnosis
zc resources create --kind K [--subtype S] --label L [--set k=v] Stage a new node
zc resources set ID --set k=v Stage an edit
zc resources rm ID Stage a delete
zc describe kinds, zc describe kind SUBTYPE What you can create, its settings and the variables it injects
zc link FROM TO, zc unlink LINK_ID Stage a link or its removal
zc env keys ID, zc env set ID KEY=VALUE List variable names (values are never shown), set values
zc plan Pending changes, quota effect and the plan hash
zc deploy [--plan-hash H] Request or apply a deploy
zc push APP [DIR] Upload a folder as the app’s code and build it (respects .gitignore, leaves out .env and keys)
zc git setup APP Add a git push remote for the app
zc repo connect APP URL [--branch B] Connect a GitHub repository
zc refs APP, zc pull APP [--branch B | --tag T | --commit SHA] List refs, build and track one
zc rollback APP --to TAG|SHA Go back to a tag or commit
zc source ls APP, zc source cat APP PATH Read an uploaded app’s code
zc publish-github APP ORG/REPO [--create] Push an uploaded app’s code to a GitHub repository and link it
zc export, zc apply -f FILE Infrastructure as code: see zedcloud.yaml
zc templates list / show / use Ready-made apps: see Templates
zc init Write .zc and a starter zedcloud.yaml (--agents-md adds a section to AGENTS.md)
zc tools --format anthropic|mcp|openai Print tool definitions for agent frameworks
zc mcp Run a local MCP server: see AI agents

Exit codes

Section titled “Exit codes”
Code Meaning
0 OK
2 Usage error
3 Not signed in, missing scope, or forbidden
4 Needs a person: staged, waiting for Deploy or approval
5 Plan, billing or suspended account
6 Rate limited
7 Validation error
8 Conflict: something changed since you read it

--json (or ZC_OUTPUT=json) prints raw JSON; errors go to stderr as {code, message, hint}.