Skip to main content

gws init

gws init scaffolds the project shell in your repository. It does not generate gws.json, scan dependencies, or create a cluster — those steps are driven by an AI coding agent via /gws-setup, or by you running gws config import on a hand-authored gws.json.

If you're new here, start with the Zero-Config Setup with AI guide first.

Usage​

gws init

Output:

? Project name: my-project

✓ Project 'my-project' registered (ID: 42).

✓ gws init complete.
Next: tell your AI agent `/gws-setup` to generate gws.json and deploy.
No AI? Hand-author gws.json and run `gws config import gws.json`.

Behind that minimal output, gws init also:

  • Writes .gws/.gitignore (ignores ephemeral artifacts inside .gws/).
  • Appends a managed block to your root .gitignore that ignores gws.json and .gws/setup-diagnostic.md — the canonical config lives in the API, so the local file is a transport artifact, not source of truth.
  • Appends the GWS context block to AGENTS.md / CLAUDE.md if either exists (so your AI agent knows how to drive /gws-setup).

Note: must be run from inside your project directory. Authentication is not required — gws init works before gws login so a fresh user can scaffold immediately. The API registration step is best-effort; if you're offline or unauthenticated, it skips and you can wire up the API later via gws login + gws config import.

Arguments and options​

gws init takes no positional arguments and no options. The only interactive prompt is the project name.

If you migrated from an older release: the --force and --from-file <path> flags were removed in Phase 2 of the zero-config-setup plan. Use gws config import gws.json instead of gws init --from-file gws.json.

What gws init does​

  1. Prompts for a project name (validated as a npm-package-style slug).
  2. Best-effort registers the project shell with the GetWebstack API.
  3. Writes .gws/.gitignore with the standard exclusions (state.json, tunnels/, etc.).
  4. Appends a .gws/ block to the repo-root .gitignore (idempotent).
  5. Only if AGENTS.md and/or CLAUDE.md already exist at the repo root, appends a GWS context block between <!-- gws:start --> / <!-- gws:end --> markers. The content above and below the markers is preserved; only what's between them is overwritten on re-run.
  6. Prints the next-steps message.

If neither AGENTS.md nor CLAUDE.md exists, gws init prints a tip recommending you create one and re-run it — rather than silently bootstrapping an opinionated file.

After gws init​

Pick one path:

/gws-setup

The skill generates gws.json, deploys, validates, and iterates. See Zero-Config Setup with AI.

Without an AI agent​

gws schema --json > schema.json   # for IDE autocomplete
$EDITOR gws.json                   # write your config
gws config validate gws.json       # local schema check
gws config import gws.json         # push to API
gws up                             # deploy

Troubleshooting​

Project name is taken​

Pick a different slug or change the existing project's name from the dashboard.

"Could not register project — continuing offline"​

Network or auth issue. gws init continues anyway; run gws login later, then gws config import will register the project on first push.

My AI agent isn't picking up /gws-setup​

Re-run gws skills install (creates the symlinks under ~/.claude/skills/ and ~/.agents/skills/), then restart the agent.

See also​