Overview

GWS CLI (gws) provides commands to manage your projects and worktrees in a local Kubernetes development environment.

---

Command Categories

Authentication

• gws login - Authenticate with GetWebstack API

Project Setup

• gws init - Register project shell, write .gws/.gitignore, append GWS context block to AGENTS.md / CLAUDE.md

Configuration & AI

• gws config - Round-trip gws.json between repo and API (import / export / diff / validate)
• gws secret - Store, list, and delete encrypted secrets
• gws skills - Install AI skills (/gws-setup, /gws-up, /gws-status, /gws-down, /gws-debug)

Worktree Management

• gws fork - Create isolated worktree
• gws delete - Delete worktree and cleanup

Deployment

• gws cluster up - Provision cluster + all shared infrastructure without deploying a project (idempotent; use as CI/eval pre-flight)
• gws cluster down - Tear down one environment's cluster (env-scoped)
• gws up - Deploy to Kubernetes cluster
• gws down - Stop deployment and cleanup

Monitoring & Debug

• gws status - View deployment status and URLs
• gws logs - View service logs
• gws exec - Execute commands in service container
• gws expose - Expose port to service container

AI helper commands

These are mostly invoked by the /gws-setup skill, but available for direct use.

• gws schema - Emit the live JSON schema for gws.json (--json for raw)
• gws detect - Detect framework, language, and port; emits stable JSON
• gws generate-template - Emit a known-good Dockerfile or K8s manifest for a framework
• gws generate-helm-values - Emit Helm values for a common dev dependency
• gws doctor - Diagnose Dockerfile / manifest / cluster issues

Maintenance & advanced

• gws update - Self-update the CLI (and refresh skill symlinks)
• gws apply - Apply ad-hoc K8s manifests to the active deployment
• gws rebuild - Rebuild and redeploy a single service
• gws profile - List configuration profiles defined in gws.json

---

Quick Reference

Command	Description	Parameters
gws login	Authenticate	None
gws init	Register project shell	None (interactive name prompt)
gws config <import|export|diff|validate>	Manage gws.json	--name [slug], --json
gws secret <set|list|delete>	Manage encrypted secrets	--service [svc], --worktree [w], --stdin, --value, --type
gws skills install	Install AI skills	--force, --json
gws fork <worktree-name>	Create worktree	-p [project], --branch [branch-name]
gws up	Deploy to k8s	-w [worktree], -p, --profile [name], -e [env], -y, --sequential
gws down	Stop deployment	-w [worktree], -p [project], -y, --delete-cluster
gws delete	Delete worktree	-w [worktree], -p [project], -y, --keep-branch
gws status	View status	-w [worktree], -p [project], --json
gws logs [service]	View logs	-w [worktree], -p [project], -f, --tail, --since
gws exec <service>	Execute command	-w [worktree], -p [project], -i, -t, -c [container], --shell
gws expose add <service>	Expose port	-w [worktree], -p [project], --local-port, --remote-port
gws schema	Emit gws.json JSON Schema	--json
gws detect	Detect frameworks/ports	--path [dir]
gws generate-template <framework> <kind>	Emit a Dockerfile / K8s template	--name, --port, --list
gws generate-helm-values <chart>	Emit Helm values	--format yaml|json, --name, --list
gws doctor	Diagnose project artifacts	-p, -w, --service, --artifacts-only, --json
gws update	Self-update CLI	--check, --force, --target [version]
gws apply <manifest>	Apply manifests to active deployment	-w [worktree]
gws rebuild <service>	Rebuild and redeploy one service	-w [worktree]
gws profile	List configuration profiles	None

---

Common Parameters

Most commands support these parameters to run from any directory:

Parameter	Description	Default Behavior
-p, --project <name>	Target project name	Auto-detected from current directory
-w, --worktree <name>	Target worktree name	Main project deployment (not a worktree)

gws up exception: for gws up, -p is the short form of --profile (configuration profile), not --project. Project is always auto-detected for gws up.

How it works:

• Without -p: Command searches for project in current directory
• Without -w: Command applies to the main project deployment (not a worktree)
• With both: Command can run from anywhere and target any project/worktree

Examples:

# Run from project directory (uses current directory as project)
cd /path/to/myapp
gws up -w feature-auth

# Run from anywhere (specify both project and worktree)
gws up -p myapp -w feature-auth

# Deploy main project (no worktree)
gws up -p myapp

---

Global Options

Available for all commands:

Option	Description
-v, --verbose	Verbose output
--debug	Debug mode (very verbose)
-y, --yes	Auto-confirm all prompts
--version	Show CLI version
--help	Show command help