> ## Documentation Index
> Fetch the complete documentation index at: https://docs.westyx.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Command reference

> Complete reference for all westyx CLI commands.

## Global flags

Available on every command:

| Flag                   | Description                                       |
| ---------------------- | ------------------------------------------------- |
| `--tenant <id\|name>`  | Override the active tenant for this command       |
| `--project <id\|name>` | Override the active project for this command      |
| `--format <format>`    | Output format: `table` (default), `json`, `plain` |
| `--quiet` / `-q`       | Suppress success messages and interactive prompts |
| `--endpoint <url>`     | Override the API endpoint                         |
| `--no-browser`         | Force device flow for `westyx login`              |
| `--help` / `-h`        | Show help                                         |

## Environment variables

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

| Variable            | Equivalent flag | Description                                       |
| ------------------- | --------------- | ------------------------------------------------- |
| `WESTYX_TOKEN`      | -               | Access token for CI/CD - bypasses all OAuth flows |
| `WESTYX_TENANT`     | `--tenant`      | Active tenant                                     |
| `WESTYX_PROJECT`    | `--project`     | Active project                                    |
| `WESTYX_ENDPOINT`   | `--endpoint`    | API endpoint                                      |
| `WESTYX_NO_BROWSER` | `--no-browser`  | Force device flow                                 |

***

## Auth

### `westyx login`

Authenticate and store credentials.

```bash theme={null}
westyx login [--no-browser] [--force]
```

| Flag           | Description                                       |
| -------------- | ------------------------------------------------- |
| `--no-browser` | Force device flow even on machines with a display |
| `--force`      | Skip the "already logged in" prompt               |

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

### `westyx logout`

Clear stored credentials. Active tenant and project context is preserved.

```bash theme={null}
westyx logout
```

### `westyx version`

Print the CLI version.

```bash theme={null}
westyx version
# westyx v0.5.0 (linux/amd64)
```

***

## Context

### `westyx tenant list`

List tenants you belong to.

```
  ID                                    NAME              ROLE      ACTIVE
  a1b2c3d4-e5f6-7890-abcd-ef1234567890  Acme Digital      owner     *
  b2c3d4e5-f6a7-8901-bcde-f12345678901  Startup Inc       member
```

### `westyx tenant set <id|name>`

Set the active tenant.

```bash theme={null}
westyx tenant set acme-digital
```

### `westyx project list`

List projects in the active tenant.

### `westyx project set <id|name>`

Set the active project.

```bash theme={null}
westyx project set backend
```

***

## Analyze

```bash theme={null}
westyx analyze [path] [flags]
```

Reads a `.env` file, classifies each entry, and writes a `.wx` file for review.

| Flag                   | Default       | Description                                          |
| ---------------------- | ------------- | ---------------------------------------------------- |
| `[path]`               | `.env`        | Path to the `.env` file                              |
| `--service=<id\|name>` | -             | Map all entries to an existing service               |
| `--output <path>`      | `.westyx/.wx` | Output path                                          |
| `--monorepo`           | off           | Group entries by service prefix (multi-service mode) |

**Classification rules** (applied in order):

| Entry                                                                      | Classified as |
| -------------------------------------------------------------------------- | ------------- |
| Value is `true` or `false`                                                 | `flag`        |
| Key contains `password`, `secret`, `token`, `api_key`, `private_key`, etc. | `secret`      |
| Value matches credential URL pattern (`://user:pass@`)                     | `secret`      |
| Everything else                                                            | `config`      |

**Output:**

```
✓ Analyzed 18 entries -> .westyx/.wx

  secret   7
  config   9
  flag     2

Review .westyx/.wx, then run:
  westyx dev push
```

***

## Developer workflow (`westyx dev`)

### `westyx dev push`

Push a `.wx` file to your personal Nexus dev environment.

```bash theme={null}
westyx dev push [path] [--overwrite] [--ask]
```

| Flag          | Default       | Description                       |
| ------------- | ------------- | --------------------------------- |
| `[path]`      | `.westyx/.wx` | `.wx` file to push                |
| `--overwrite` | off           | Force-overwrite all existing keys |
| `--ask`       | off           | Prompt on conflict                |

Conflict behaviour per entry:

| Situation                                        | Default | `--overwrite` | `--ask` |
| ------------------------------------------------ | ------- | ------------- | ------- |
| Key does not exist                               | CREATED | CREATED       | CREATED |
| Key exists                                       | SKIPPED | UPDATED       | Prompt  |
| Key exists, `on_conflict = "overwrite"` in `.wx` | UPDATED | UPDATED       | UPDATED |

**Output:**

```
  CREATED  secret  db_password
  SKIPPED  config  max_retries    (exists - on_conflict: keep)
  UPDATED  config  log_level      (on_conflict: overwrite)
Push complete: 2 created · 1 updated · 1 skipped
```

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 entire project's current state to a `.wx` file.

```bash theme={null}
westyx dev pull [--output <path>] [--service=<id|name>]
```

| Flag                   | Default       | Description           |
| ---------------------- | ------------- | --------------------- |
| `--output <path>`      | `.westyx/.wx` | Output path           |
| `--service=<id\|name>` | all           | Pull one service only |

### `westyx dev setup`

Configure Developer WIF credentials for a service. After setup, the Nexus SDK detects the
credentials automatically - no `api_key` needed in your local config.

```bash theme={null}
westyx dev setup --service=<id|name> [--ttl <duration>]
```

Credentials are stored at `~/.config/westyx/dev-credentials.yaml` (`0600`).

Scope by tier:

| Tier          | Accessible environments |
| ------------- | ----------------------- |
| `free`, `xs`  | `develop` (personal)    |
| `s` and above | `develop`, `test`       |

Production environments are never accessible via Developer WIF.

### `westyx dev run`

Start a process with Nexus values injected as environment variables.

```bash theme={null}
westyx dev run [script-name] [-- command]
```

Scripts are defined in `.westyx/config`:

```bash theme={null}
westyx dev run              # default_script from .westyx/config
westyx dev run start        # named script
westyx dev run test         # named script
westyx dev run -- go run .  # ad-hoc command, default .wx profile
```

When Nexus is unreachable, values are read from `.westyx/.wx` as a fallback.

Key name transformation on injection: uppercased, dots and hyphens replaced with underscores.
(`max.retries` becomes `MAX_RETRIES`)

### `westyx dev status`

Show Developer WIF credential state.

```
  SERVICE           ENDPOINT                                EXPIRES     STATUS
  my-backend-api    https://swift-ocean-a5rx7.westyx.dev    in 6h 42m   valid
  payments          https://bold-river-9xk2m.westyx.dev     expired     expired
```

### `westyx dev teardown`

Remove Developer WIF credentials.

```bash theme={null}
westyx dev teardown --service=<id|name>
westyx dev teardown --all
```

***

## Secrets

```bash theme={null}
westyx secret get <key>            [--service=<id|name>] [--env=<env>]
westyx secret set <key> <value>    --service=<id|name>   [--env=<env>]
westyx secret list                 [--service=<id|name>] [--env=<env>]
```

* `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.
* `list` masks values in `table` output (`***`). Use `--format=json` or `--format=plain` to
  retrieve the actual value.

```bash theme={null}
westyx secret get DB_PASSWORD --service=payments --format=plain
```

***

## Configs

```bash theme={null}
westyx config get <key>            [--service=<id|name>] [--env=<env>]
westyx config set <key> <value>    --service=<id|name>   [--env=<env>]
westyx config list                 [--service=<id|name>] [--env=<env>]
```

`set` is an upsert - creates or updates the key.

***

## Feature flags

```bash theme={null}
westyx flag get <key>              [--service=<id|name>] [--env=<env>]
westyx flag set <key> <value>      --service=<id|name>   [--env=<env>]
westyx flag list                   [--service=<id|name>] [--env=<env>]
```

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

***

## Output formats

| Format  | Description                                               |
| ------- | --------------------------------------------------------- |
| `table` | Aligned columns with headers (default for list commands)  |
| `json`  | Compact JSON - stable, suitable for scripting             |
| `plain` | One value per line, no headers - for `grep`/`awk`/`xargs` |

`plain` on list commands prints the primary identifier (e.g. tenant name) one per line.
`plain` on single-value commands (`get`) prints the bare value.

***

## Exit codes

| Code | Meaning         | When                                                    |
| ---- | --------------- | ------------------------------------------------------- |
| `0`  | Success         | Command completed as requested                          |
| `1`  | General error   | Network failure, unexpected server error                |
| `2`  | Usage error     | Invalid flags, missing arguments, ambiguous name        |
| `3`  | Auth error      | Not logged in, session expired, permission denied (403) |
| `4`  | Partial success | `dev push` when some entries succeed and others fail    |

***

## 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.

```hcl theme={null}
workspace {
  tenant  = "acme-digital"
  project = "backend"
}

defaults {
  on_conflict = "keep"   # keep | overwrite | ask
}

service "payments" {
  id   = "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  type = "backend"   # backend | frontend | umbrella
}

secret "stripe_api_key" {
  service     = "payments"
  value       = "sk_live_abc123"
  on_conflict = "overwrite"   # overrides defaults block
}

config "max_retries" {
  service = "payments"
  value   = "3"
}

flag "new_checkout" {
  service = "payments"
  value   = false
}
```

The `on_conflict` field on individual blocks overrides the `defaults` block.

<Note>
  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.
</Note>

## The `.westyx/config` file

Committed to git. Contains workspace context and `westyx dev run` script definitions.

```hcl theme={null}
workspace {
  tenant  = "acme-digital"
  project = "backend"
}

run {
  default_script = "start"
}

script "start" {
  command = "go run main.go"
}

script "dev" {
  command = "air"
}

script "test" {
  command = "go test ./..."
}

script "start-staging" {
  profile = "staging"      # uses .westyx/staging.wx
  command = "go run main.go"
}
```

`profile` points to a named `.wx` file in `.westyx/` (without the `.wx` extension). Defaults to
`.wx` (the dot-prefixed default file).