Agent-Skills.md

Agent Skills: ZStack CLI

Use when operating ZStack through its first-party `zstack` CLI, including logging in, creating API tokens, listing workspaces, deploying environments, streaming logs, wiring domains, managing resources/units, or opening runtime shells for ZStack-backed apps.

UncategorizedID: idanbeck/claude-skills/zstack-cli

Repository

idanbeck/claude-skills
idanbeck
123

Install this agent skill to your local

pnpm dlx add-skill https://github.com/idanbeck/claude-skills/tree/HEAD/zstack-cli

Skill Files

Browse the full folder contents for zstack-cli.

Download Skill

Loading file tree…

zstack-cli/SKILL.md

Skill Metadata

Name
zstack-cli
Description
Use when operating ZStack through its first-party `zstack` CLI, including logging in, creating API tokens, listing workspaces, deploying environments, streaming logs, wiring domains, managing resources/units, or opening runtime shells for ZStack-backed apps.

ZStack CLI

Use the zstack CLI instead of scraping the ZStack web UI whenever you need to inspect or operate workspaces, deployments, resources, domains, deploy logs, runtime DB/files/secrets, admin capacity, GitHub source discovery, or shell access.

Defaults

  • Run from /Users/idanbeck/zerg-stack/zstack unless the user asks for another repo.
  • CLI source lives in cli/zstack.
  • Config is ~/.config/zstack/config.json; environment overrides are ZSTACK_BASE_URL, ZSTACK_TOKEN, ZSTACK_SESSION_TOKEN, ZSTACK_WORKSPACE, ZSTACK_CONFIG_PATH.
  • Prefer API tokens for automation. Browser session login is fine for local operator tasks.
  • Prefer JSON-returning commands for scripts and agents.

Build

cd /Users/idanbeck/zerg-stack/zstack/cli/zstack
go build -o zstack .

Use ./zstack ... from the build directory or install the binary onto PATH.

Common Workflows

Authenticate:

zstack auth login --email "$EMAIL" --password "$PASSWORD"
zstack auth whoami

Create a workspace-bound automation token:

zstack auth token create \
  --name agent \
  --workspace zstack \
  --scope workspace:write \
  --scope deploy:write \
  --scope resource:write \
  --scope domain:write

Inspect workspaces and deployments:

zstack workspace list
zstack workspace show zstack --json
zstack workspace branches --workspace zstack
zstack workspace branch-deploy --workspace zstack --source-env <environment-id> --branch feature/foo
zstack deploy list --app zstack --limit 20

Deploy and follow logs:

zstack env deploy --id <environment-id> --follow
zstack deploy logs <deploy-id> --follow

Open runtime shell:

zstack shell --env <environment-id>

Wire a domain:

zstack domain wire --env <environment-id> --hostname dev.example.com --provider godaddy --zone example.com

Manage resource topology:

zstack resource list --workspace zstack
zstack unit list --env <environment-id>
zstack resource promote --workspace zstack --unit-id <unit-id> --name shared_database
zstack env resources show --env <environment-id>
zstack env resources scale --env <environment-id> --vm-size shared-cpu-2x
zstack unit backup <unit-id>

Inspect runtime data and files:

zstack db info --env <environment-id>
zstack db table --env <environment-id> --schema public --table users --limit 20
zstack db query --env <environment-id> --sql 'SELECT now()'
zstack files list --env <environment-id> --path /app
zstack files download --env <environment-id> --path /app/file.txt --out file.txt
zstack secrets list --env <environment-id>

Admin and source discovery:

zstack github repos --owner Epoch-ML
zstack github branches --owner Epoch-ML --repo zerg
zstack admin overview
zstack admin capacity
zstack admin queue reconcile

Safety

  • Do not run restart, suspend, resume, rollback, domain delete, or resource topology mutations unless the user asked for the operation or it is clearly required by the task.
  • For production environments, show the target workspace/environment before mutating.
  • If a command returns a deploy id, use log streaming to verify the deploy completed.