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.
--env (secret/config/flag get|set|list, snapshot list|create, service list|get):
--envflagWESTYX_ENVenvironment variable.westyx/configworkspaceenvironmentfield- Global config’s persisted default (set via
environment set) - Empty - the server resolves your personal environment, or (for a list-shaped command) shows every environment
--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:
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
.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:
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.
--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.
- Workspace. With no
.westyx/configin a project directory (one with.git,.envor.westyx), it writes one from the active tenant, project and environment. Outside a project it writes nothing. - Values. With no
.westyx/.wx, it pulls the values when the project already has services in Nexus; otherwise it analyzes.envinto.westyx/.wxfor you to review and upload withwestyx dev push, and offers to remove theWESTYX_*connection settings from.env. An existing.wxis never overwritten. - Default script. When
.westyx/confighas no script yet, it recognises the project and writes adevscript that starts it, as the default (run { default_script = "dev" }). The script names the service given with--service, or the project’s only service. - Credentials. It issues a Developer WIF session for every service a script in
.westyx/confignames - one login, one session per service - or for--serviceonly. A failure for one service does not discard the others. - 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 (seewestyx 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.
.westyx/config, or an ad-hoc command can be passed directly after -- without a run block:
--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):
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
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
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
getwithout--servicesearches all non-umbrella services; exits 2 if the key exists in more than one service.setalways creates a new version - secrets are versioned and cannot be overwritten.getandlistboth mask values intableoutput (***). Use--format=jsonor--format=plainto retrieve the actual value.- A secret that is declared without a value shows as
(not set), and as"not_set": truein JSON.get --format=plainon 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 .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.
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.
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).