Skip to main content

Global flags

Available on every command:

Environment variables

Priority: explicit flag > env var > .westyx/config > global config > default

Auth

westyx login

Authenticate and store credentials.
On success, the CLI auto-selects the first tenant and project.

westyx logout

End the session and remove everything of the account from this machine: the login is revoked at the server, and the stored login, the active tenant, project and environment, and the Developer WIF credentials are removed. To switch accounts, log out and log in. If the server cannot be reached the local state is still removed, and the command says the login stays valid at the server until it expires. An --endpoint override is kept - it belongs to the machine, not the account.

westyx version

Print the CLI version.

Upgrade

westyx upgrade

Fetch and install a newer release manifest, or check availability without installing.
An exact --version older than the running binary shows a downgrade confirmation (default N; non-interactive stdin exits 2 without --force). A background update check runs once per invocation and prints a one-line notice on stderr when a newer stable version is available, without blocking the command.

Context

westyx tenant list

List tenants you belong to.

westyx tenant set <id|name>

Set the active tenant.

westyx project list

List projects in the active tenant.

westyx project set <id|name>

Set the active project.

westyx environment list

Show the active project’s tier and its allowed environment names. The list includes your own personal developer environment, if you have one in this project, so it can be selected with westyx environment set - other developers’ personal environments are not shown.
ACTIVE marks whichever environment is currently active for this invocation, from any resolution tier below - including a transient WESTYX_ENV override.

westyx environment set <name|all>

Persist a default environment, validated against the tier’s allowed set.
Environment resolution priority for every command that takes --env (secret/config/flag get|set|list, snapshot list|create, service list|get):
  1. --env flag
  2. WESTYX_ENV environment variable
  3. .westyx/config workspace environment field
  4. Global config’s persisted default (set via environment set)
  5. Empty - the server resolves your personal environment, or (for a list-shaped command) shows every environment
Whenever the resolved environment came from tier 3 or 4 - never from an explicit --env or WESTYX_ENV, which you already see in what you typed - the CLI prints a one-line notice on stderr before running, suppressed by --quiet:
The notice is not printed when you pass a UUID rather than a name - westyx service get <uuid>, or --service=<uuid> on a secret/config/flag command. A UUID identifies one service outright, so the environment is not consulted and there is no filter to announce.

Analyze

Reads a .env file, classifies each entry, and writes a .wx file for review. The file’s workspace is filled from the active tenant and project. WESTYX_* entries - how an application connects to Nexus, not values to keep in it - are skipped, each one named in the output. Classification rules (applied in order): Matching is word-boundary based, not substring: AUTH_TOKEN matches (auth and token are whole segments) but AUTHOR_NAME does not. westyx analyze prints no summary on success - it writes the .wx file silently (exit 0) and adds *.wx / !.westyx/example.wx to the nearest .gitignore on first write. Review the generated file, then run westyx dev push.

Developer workflow (westyx dev)

westyx dev push

Push a .wx file to your personal Nexus dev environment.
--overwrite and --ask are mutually exclusive (exit 2 if both are set). In non-interactive mode (no TTY on stdin), --ask has no effect and silently falls back to keep, printing a warning first. Conflict behaviour per entry: Output:
A secret whose value is empty is not pushed (SKIPPED ... no value): an empty value is not a value, and the secret keeps whatever state it has in Nexus. If a service block has an empty id, the service is created in Nexus and the assigned UUID is written back into the .wx file.

westyx dev pull

Download the current state of one environment’s services to a .wx file.
The pull is scoped to the active environment (--env, then WESTYX_ENV, then .westyx/config, then your default). A .wx file holds one environment: when no environment is set and the project has the same service name in more than one, the pull stops and asks for --env instead of mixing their values.

westyx dev setup

The one command that sets up local development. Run it in a project; re-run it at any time - it does only what is missing.
  1. Workspace. With no .westyx/config in a project directory (one with .git, .env or .westyx), it writes one from the active tenant, project and environment. Outside a project it writes nothing.
  2. Values. With no .westyx/.wx, it pulls the values when the project already has services in Nexus; otherwise it analyzes .env into .westyx/.wx for you to review and upload with westyx dev push, and offers to remove the WESTYX_* connection settings from .env. An existing .wx is never overwritten.
  3. Default script. When .westyx/config has no script yet, it recognises the project and writes a dev script that starts it, as the default (run { default_script = "dev" }). The script names the service given with --service, or the project’s only service.
  4. Credentials. It issues a Developer WIF session for every service a script in .westyx/config names - one login, one session per service - or for --service only. A failure for one service does not discard the others.
  5. Frontend dev server. For a frontend service it prepares the framework’s dev server to proxy /__westyx, the path the browser SDK fetches its developer session from (see westyx dev run).
The Node.js package manager is the packageManager field of package.json, else the one lockfile present (bun.lock, pnpm-lock.yaml, yarn.lock, package-lock.json), else npm. With several lockfiles and no packageManager field, or a project with no standard run command, no script is written. The dev server is prepared per framework: It never overwrites anything: an existing script, a run block, a proxyConfig, an existing proxy.conf.mjs, or an angular.json that has comments or several applications is left as it is. Whatever it could not do itself is printed at the end of setup under !!! IMPORTANT - finish setup by hand, with the exact lines and the file they go in. With --format json the same list is written as {"actions":[{"title","file","lines","why"}]}. The per-framework entries are also on the Angular, React and Vue SDK pages. Credentials are stored at ~/.config/westyx/dev-credentials.json (0600), one entry per service endpoint. After setup, start your app with westyx dev run. What it requires. An authenticated session (westyx login), membership of the service’s project with a role listed in the project’s Security add-on Developer WIF role list, and that add-on enabled. Nothing else: no workload trust policy, and no API key on the machine. How the workload authenticates is not part of it. A service that runs in production on a wxs_ API key can still be developed against locally with Developer WIF, because a trust policy answers “which workload is this” while Developer WIF answers “which developer is this”. The two environments need not agree. A Developer WIF session never covers a production environment, whatever the tier - see the table below. A Developer WIF session reaches the project’s non-production environments: those of its tier that are classed as non-production, plus your own personal developer environment if you have one. Both are platform configuration, so the table below is the default, not a fixed rule. staging is classed as production-grade and is not reachable; prod, prod-blue and prod-green never are, whatever the configuration. Plus, on every tier, your own personal environment (dev-<you>) - never another developer’s.

westyx dev run

Start a process with Nexus values injected as environment variables.
Scripts are defined in .westyx/config, or an ad-hoc command can be passed directly after -- without a run block:
A script (or --service on westyx dev run) can name the service it runs as, and then westyx dev run passes that service’s endpoint to the process as WESTYX_SERVICE_ENDPOINT. A Nexus SDK reads it when its configuration names no endpoint, and finds your Developer WIF credential by it - so the application needs no endpoint and no key in its code. A repository with several services has one script per service. The process then receives the values of that service only, so two services that share a key name do not collide. Before it starts the process, dev run checks that you have a Developer WIF credential for that service with at least five minutes left, and otherwise stops with the command that fixes it (westyx dev setup --service=<name>). The token itself is never put in the process’s environment. A Developer WIF session reaches only non-production environments. When the script’s service is in an environment the session does not reach - prod, for example - dev setup and dev run say so and name the environments it does reach; the process still starts, and a Nexus SDK using the session there is refused. Switch with westyx environment set <name>. A secret that is declared without a value - one imported into a personal environment, for example - is named in a warning before the process starts, with the command that sets it. The application does not receive such a secret, so this is where you learn about it. The warning is printed with --quiet too, and never stops the run. Frontend services. A script whose service is a frontend service runs as a child of dev run instead of replacing it, next to a session broker on 127.0.0.1 that lives as long as the process. Its address is passed as WESTYX_DEV_BROKER; the dev server proxies /__westyx to it, and the browser SDK - configured with neither baseUrl nor apiKey - fetches the endpoint and the current session from /__westyx/session on its own origin. The broker reads dev-credentials.json on every request, so re-running westyx dev setup while the app runs is picked up. Its address carries a random per-run secret, which is why dev run never prints it. Only the dev server proxies the path, so a production build never reaches a session. When the dev server’s configuration has no /__westyx entry, dev run warns and starts anyway. Ctrl+C stops the dev server and dev run together, and dev run exits with the dev server’s exit code. When Nexus is unreachable, values are read from .westyx/.wx and the endpoint from your Developer WIF credential. Values dev run injects take precedence over the same names inherited from your shell. Key name transformation on injection: uppercased, dots and hyphens replaced with underscores. (max.retries becomes MAX_RETRIES) Before the process’s own output, dev run prints on stderr what it started (suppressed by --quiet):
A frontend script has one more line, browser /__westyx -> session broker (WESTYX_DEV_BROKER). The names come from the comment line in .westyx/config, and the ids are shown when it is absent. The values line says from .wx cache (Nexus unreachable) when Nexus could not be reached, and the service line says (from your Developer WIF credential) when the endpoint came from there. A script that names no service shows none - no endpoint exported and no auth line. Only counts are printed - never a value, a token or a variable name. With --verbose / -v the banner also lists the variables by kind and name - still without their values - for when you are looking for one that is missing:

westyx dev status

Show Developer WIF credential state.

westyx dev teardown

Remove Developer WIF credentials.
--service and --all are mutually exclusive; exactly one is required. --yes / -y skips the confirmation prompt (only asked for --all).

Services

Table output columns: ID, NAME, KIND, ENV, ENDPOINT, UMBRELLA (✓ / -). get renders through the same row type as list, just with one row. <id|name> resolves the same way every --service flag does: a UUID resolves directly; a name is matched by listing, and --env disambiguates a same-named service across environments. create requires --name and --env - a service belongs to exactly one environment. --kind defaults to backend, --auth-mode defaults to api_key. Tier limits, WIF prerequisites (auth-mode=wif needs the project’s Security add-on and at least one trust policy) and name collisions are reported by the server.
delete requires project owner or manager, prompts for confirmation unless --yes, and deletes the service and everything scoped to it (secrets, configs, flags, keys). Refused with an error if the target is an umbrella that still has services linked to it - unlink them first.

Snapshots

Table output columns for list: ID, NAME (- if unnamed), ENV, CREATED, AUTO-DELETE (in N days / keep), SERVICES (count). create defaults to a 7-day auto-delete; --auto-delete-days=never pins the snapshot. 409 snapshot_cap_exceeded from the API is surfaced as-is. diff shows secrets as changed/unchanged only (values are never printed), configs with their actual before/after values, and flags with their enabled state. Services deleted since the snapshot show STATUS: deleted_since; services added since show STATUS: added_since. restore is atomic - the backend applies every targeted service in one transaction, so a failure leaves nothing changed. Without --yes it prints the diff summary and prompts before restoring. --save-before takes a backup snapshot first and aborts the restore if that backup fails. --service-ids (comma-separated UUIDs, from snapshot list/diff output - names are not accepted) selects a subset for restore. delete requires manager+ role and prompts for confirmation unless --yes.

Secrets

  • get without --service searches all non-umbrella services; exits 2 if the key exists in more than one service.
  • set always creates a new version - secrets are versioned and cannot be overwritten.
  • get and list both mask values in table output (***). Use --format=json or --format=plain to retrieve the actual value.
  • A secret that is declared without a value shows as (not set), and as "not_set": true in JSON. get --format=plain on it exits with an error and prints nothing, so a script never reads an empty line as the value.

Configs

set is an upsert - creates or updates the key.

Feature flags

set value must be true, false, 1, or 0.

Output formats

plain on tenant list / project list prints the primary identifier (name) one per line. plain on secret/config/flag list prints KEY=VALUE one per line. plain on single-value commands (get) prints the bare value.

Exit codes

A failure prints Error: <message> on stderr. The Usage: block follows only for a usage error (exit 2), where the usage text is the answer; a runtime failure prints the error alone. Under --format json the failure is a single-line JSON object on stderr instead, with a fixed shape for every command - error carries the server’s machine-readable code when it named one, and is empty otherwise:
The exit code is the same in both formats.

The .wx file format

.wx files are the local representation of your Nexus resources. They are gitignored (contain real secret values) and human-editable. westyx analyze and westyx dev pull both generate them.
The on_conflict field on individual blocks overrides the defaults block.
Commit .westyx/example.wx as a structure template for new team members. Never commit .wx files with real values. westyx analyze adds *.wx to .gitignore automatically.

The .westyx/config file

Committed to git. Contains workspace context and westyx dev run script definitions. westyx dev setup creates it; tenant set, project set and environment set keep it current.
The workspace holds ids, so it survives a rename and needs no lookup offline; the comment line above it names them for a reader and is maintained by the CLI. A hand-written file that uses names still works while Nexus is reachable - the CLI resolves them. The format is one key = "value" per line: put a comment on a line of its own, not after a value. profile points to a named .wx file in .westyx/ (without the .wx extension). Defaults to .wx (the dot-prefixed default file).