workshop-cli

Command-line interface for the Workshop platform. Manage organizations, projects, services, deployments, infrastructure, secrets, and observability from your terminal.

Installation

From npm (recommended)

@secretstartups/workshop is published to the public npm registry — no setup required:

npm install -g @secretstartups/workshop
# workshop <command> now works from anywhere

Updating

Global installs are pinned and do not auto-update. Check your version and update to the latest release:

workshop --version                              # also -v / -V
npm install -g @secretstartups/workshop@latest  # update to the newest release

From 0.1.2 onward the CLI nudges you (once a day) when a newer version is available, so you only need to run the update command when prompted.

From source (for contributors)

cd workshop-cli
npm install
npm run build

Link the binary globally (optional):

npm link
# workshop <command> now works from anywhere

Or run directly from the project directory:

./dist/main.js <command>

Quick Start

# 1. Point at your API (defaults to http://localhost:3000/api/v1)
workshop config set-url https://api.yourworkshop.com

# 2. Log in
workshop auth login

# 3. List and select your active organization
workshop org list
workshop org use <orgId>

# 4. Start managing resources
workshop project list
workshop service list --env <envId>

Commands

Auth

workshop auth login              # Log in with email and password
workshop auth logout             # Clear stored credentials
workshop auth status             # Show the currently authenticated user

workshop auth token list         # List your API tokens
workshop auth token create       # Create a new API token (interactive scope selection)
workshop auth token revoke <id>  # Revoke an API token

Organizations

workshop org list                    # List your organizations
workshop org create                  # Create an organization
workshop org get [orgId]             # Get organization details (uses active org if omitted)
workshop org delete <orgId>          # Delete an organization
workshop org use <orgId>             # Set the active organization

workshop org members list            # List members
workshop org members invite          # Invite a member
workshop org members remove <id>     # Remove a member

Projects

workshop project list                # List projects in the active org
workshop project create              # Create a project
workshop project get <projectId>     # Get project details
workshop project delete <projectId>  # Delete a project

Environments

workshop env list --project <id>     # List environments for a project
workshop env create                  # Create an environment
workshop env delete <envId>          # Delete an environment

Services

workshop service list --env <id>         # List services in an environment
workshop service create                  # Create a service
workshop service get <serviceId>         # Get service details
workshop service delete <serviceId>      # Delete a service

workshop service deploy <serviceId>      # Deploy a service to Kubernetes
workshop service status <serviceId>      # Get deployment status
workshop service logs <serviceId>        # Get pod logs
workshop service restart <serviceId>     # Restart a service
workshop service rollback <serviceId>    # Rollback to the previous deployment
workshop service stop <serviceId>        # Stop (undeploy) a service

Clusters

workshop cluster list                    # List Kubernetes clusters
workshop cluster create                  # Create a cluster (interactive wizard)
workshop cluster get <clusterId>         # Get cluster details
workshop cluster delete <clusterId>      # Delete a cluster
workshop cluster nodes <clusterId>       # List cluster nodes
workshop cluster workloads <clusterId>   # List cluster workloads

Virtual Machines

workshop vm list                    # List VMs
workshop vm create                  # Create a VM
workshop vm get <vmId>              # Get VM details
workshop vm delete <vmId>           # Delete a VM

Secrets

workshop secret list                # List secrets
workshop secret create              # Create a secret (value prompted securely)
workshop secret get <name>          # Get a secret (value masked by default)
workshop secret get <name> --reveal # Show the secret value in plaintext
workshop secret delete <name>       # Delete a secret

Observability

workshop observability status <infraId>    # Get observability stack status
workshop observability enable <infraId>    # Enable and provision the stack
workshop observability disable <infraId>   # Disable the stack

workshop observability alerts list <infraId>               # List alert rules
workshop observability alerts create <infraId>             # Create an alert rule
workshop observability alerts delete <infraId> <alertId>   # Delete an alert rule
workshop observability alerts toggle <infraId> <alertId>   # Toggle an alert on/off

Global Options

Every command supports these flags:

| Flag | Description | |---|---| | --json | Output raw JSON instead of formatted tables | | --org <orgId> | Override the active organization for this command | | --help | Show help for any command | | --version, -v, -V | Print the installed CLI version |

Configuration

The CLI stores its config at ~/.workshop/config.json:

{
  "apiUrl": "http://localhost:3000/api/v1",
  "token": "eyJ...",
  "currentOrgId": "uuid",
  "currentOrgName": "My Org"
}

You can also authenticate using a long-lived API token (useful for CI/CD):

# Generate a scoped token
workshop auth token create --name "ci-deploy" --scopes "services.update,projects.view"

# Use it in CI by writing it to config before running commands
workshop auth token create  # copy the printed token

# In CI pipeline:
node dist/main.js config set-token $WORKSHOP_TOKEN
node dist/main.js service deploy $SERVICE_ID --json

Development

npm run dev -- <command>     # Run without building (ts-node)
npm run build                # Compile to dist/
npm run lint                 # ESLint
npm run format               # Prettier

Tech Stack

• nest-commander — NestJS-powered CLI framework
• axios — HTTP client
• chalk — Terminal colours
• cli-table3 — Table output
• ora — Spinners
• @inquirer/prompts — Interactive prompts
• conf — Persistent config storage