Skip to main content

gws config

gws config is the contract between your local gws.json and the API copy. Use it to push edits, pull the canonical version, see what's drifted, or validate a config locally before importing.

Usage​

gws config <subcommand> [path] [options]
SubcommandAuth requiredDescription
importYesPush gws.json to the API
exportYesPull gws.json from the API
diffYesShow local vs API differences (CI-friendly exit code)
validateNoSchema check only — runs offline

All subcommands default to ./gws.json when [path] is omitted.

import​

Push the local gws.json to the API. Validates against the live JSON schema first; rejects anything the schema doesn't accept.

Usage​

gws config import                 # ./gws.json
gws config import path/to/gws.json
gws config import --project my-slug  # if no git remote is configured

Output:

✓ Validated gws.json against live schema.
✓ Imported config for project 'my-slug' (revision 7).

Arguments and options​

Argument / optionDescription
[path]Path to the gws.json to push. Defaults to ./gws.json.
-p, --project <name>Project name to use when no git remote is configured. Must match gws.json's name if both are present.

How the project is resolved:

  1. If -p, --project <slug> is passed, that wins.
  2. Otherwise, gws config import reads the git remotes of the current repo and matches them against the project's registered repository list.
  3. If neither matches, the command exits with ENO_PROJECT_KEY and tells you to either pass --project or wire up a git remote.

Returns a typed ENO_PERMS 403 if your account doesn't have can_change_gws_configs on the project.

export​

Fetch the API copy and write it to stdout. Redirect to a file when you want a local copy.

Usage​

gws config export              # to stdout
gws config export > gws.json   # to file

Output: the project's canonical gws.json is written to stdout as pretty-printed JSON. No status messages — the output is the file, so it's safe to redirect.

Arguments and options​

Argument / optionDescription
-p, --project <name>Project name to use when no git remote is configured. Same resolution rules as import.

gws config export does not accept a [path] argument — use shell redirection (>) to write the result to disk.

Useful when you've edited the config from the dashboard and want to sync it back into your repo.

diff​

Compute a sorted-key recursive diff between the local file and the API copy. Prints added / removed / changed keys.

Usage​

gws config diff
gws config diff path/to/gws.json
gws config diff --json          # machine-readable diff object
gws config diff --remote-only   # just print the remote config

Output:

~ services.api.replicas: 1 → 2
+ services.worker
- services.legacy

With --json, the same information is emitted as a structured {added, removed, changed} object suitable for piping into other tools.

Arguments and options​

Argument / optionDescription
[path]Local gws.json to compare against the API copy. Defaults to ./gws.json.
-p, --project <name>Project name to use when no git remote is configured.
--jsonEmit the diff as a structured JSON object instead of human-readable lines.
--remote-onlyPrint the remote config without comparing to local (handy for inspecting what's in the API).

Exit codes:

CodeMeaning
0Local and API are identical
1Local and API diverge
2Error (schema invalid, network, auth, …)

The non-zero divergence exit is intentional — it makes gws config diff safe to drop into a CI step or pre-push hook to keep the in-repo gws.json honest.

validate​

Run the JSON-schema check locally, without contacting the API. Useful in pre-commit hooks and on disconnected machines.

Usage​

gws config validate
gws config validate path/to/gws.json
gws config validate --json     # structured error output for CI

Output:

✓ gws.json is valid against the live schema.

With --json, validation errors are emitted as a structured array (one entry per schema violation) instead of human-readable lines.

Arguments and options​

Argument / optionDescription
[path]Path to the gws.json to validate. Defaults to ./gws.json.
--jsonEmit structured JSON errors instead of human-readable lines (CI-friendly).

An empty file is detected before parsing — you'll see gws.json is empty, not a raw Unexpected EOF.

To get the schema itself (for editor autocomplete or CI tooling):

gws schema --json > schema.json

gws config validate always uses this same schema, so there is no drift between local validation and the validation the API runs on import.

Common flows​

Edit and push:

$EDITOR gws.json
gws config validate
gws config import
gws up

Sync from dashboard:

gws config export > gws.json
git diff gws.json
git commit -am "chore: sync gws.json from dashboard"

CI guardrail:

gws config diff || { echo "gws.json drifted from API — run 'gws config import' or 'gws config export'"; exit 1; }

See also​