This repository is auto-generated by the Revenexx SDK Generator. Do not submit changes directly — they will be overwritten on the next generation run.

Revenexx CLI SDK

Revenexx command-line interface for managing your platform.

Installation

The Revenexx CLI is a command line tool to help you interact with the Revenexx API. Install it from npm or, on macOS and Linux, with Homebrew — the Homebrew formula installs a self-contained binary, so no Node.js is needed. Single-file binaries for every supported platform are also attached to each GitHub release for manual download.

Install using NPM

Install the CLI globally from the npm registry:

$ npm install -g @revenexx/cli

Once the installation is complete, you can verify the install using

$ revenexx -v
0.2.1

MacOS / Linux via Homebrew

The CLI ships its own tap, revenexx-sdks/homebrew-cli (Homebrew strips the homebrew- prefix, so it is addressed as revenexx-sdks/cli). No Node.js needed — the formula installs the prebuilt binary for your platform:

$ brew install revenexx-sdks/cli/revenexx

Or add the tap once and refer to the formula by name afterwards:

$ brew tap revenexx-sdks/cli
$ brew install revenexx

Upgrading to a newer release:

$ brew update && brew upgrade revenexx-sdks/cli/revenexx

revenexx update detects a Homebrew install and runs those two commands for you.

Manual download

Every release attaches a single-file binary per platform — revenexx-darwin-arm64, revenexx-linux-x64, revenexx-win-x64.exe and so on. Grab the one for your platform from the latest release, make it executable, and put it on your PATH:

$ chmod +x revenexx-darwin-arm64
$ mv revenexx-darwin-arm64 /usr/local/bin/revenexx

On Windows, use npm — or download the .exe from the same release page.

Once the installation completes, you can verify your install using

$ revenexx -v
0.2.1

Getting Started

1. Sign in

Authenticate once — the CLI stores your session under ~/.revenexx/.

# Developers: interactive SSO sign-in via the browser (Zitadel)
$ revenexx login

# CI / scripts: a gateway API key
$ revenexx login --token <token> --tenant <tenant>

Confirm who you're signed in as at any time:

$ revenexx whoami

See the Authentication section below for the full login, credential-resolution, and sign-out details.

2. Choose a tenant

Every request is scoped to a tenant. Set the active one once and the CLI remembers it:

$ revenexx tenants use <slug>
$ revenexx tenants current

3. Run a command

Each API service is exposed as a command, and every method as a subcommand. Discover them with --help:

$ revenexx --help                      # list every service
$ revenexx <service> --help            # list a service's methods
$ revenexx <service> <method> --help   # show a method's flags

For example, to list products:

$ revenexx products products-list

Ready-to-copy examples for every command are generated under docs/examples/.

4. Go faster

A few power-user conveniences once you're set up:

$ revenexx status              # identity, tenant, endpoint, token expiry & gateway health
$ revenexx p ls                # built-in aliases: same as `products list`
$ revenexx alias set deploy "apps create-deployment --activate true"
$ revenexx repl                # interactive shell — many commands, one session
$ revenexx tui                 # full-screen app — browse commands, forms, results

A production safety banner is printed before most commands showing which tenant/endpoint you're hitting (prominent and red for production). Silence it with -q/--quiet. See Command aliases, Production safety banner, status, Interactive shell (repl) and Full-screen app (tui) in the README.

Note

By default, requests to domains with self-signed SSL certificates (or no certificates) are rejected. If you trust the host, you can bypass certificate validation using

$ revenexx client --self-signed true

Three ways to use it

The CLI has one command tree reachable three ways — every service command, plugin, and alias behaves identically in all of them:

| Mode | How to start it | When | |---|---|---| | Full-screen app (tui) | bare revenexx on a terminal (the default), or revenexx tui | Browse and run interactively — the default landing experience. | | Interactive shell (repl) | revenexx repl | Fire several commands in a row without re-typing revenexx. | | Direct / one-shot | revenexx products list --json … | Scripting, CI, pipes — flag-driven and non-interactive. |

Running revenexx with no arguments on an interactive terminal launches the full-screen app. A partial or named invocation (revenexx p, revenexx products) still opens the guided command picker and resolves to a single one-shot command. Anything non-interactive — a pipe, CI, --json, or --help — prints help and never opens an interactive surface, so scripts stay byte-stable.

Opting out of the TUI default: set REVENEXX_NO_TUI=1 (any value other than 0/false) to make a bare revenexx fall back to the guided picker. For a per-project default, add a defaultMode: key to .revenexx.yaml — tui (default), guided (the picker), or help (print usage). Explicit subcommands (repl, tui, any service command) always win regardless of this setting.

Authentication

The CLI supports two ways to authenticate:

• Gateway API key — non-interactive, ideal for CI and scripts. Sent as X-Revenexx-Api-Key.
• Zitadel SSO — interactive browser sign-in for developers, using OAuth2 Authorization Code + PKCE. Mints a JWT that the CLI sends in the standard Authorization: Bearer header.

An API key always takes precedence; SSO is the fallback when no key is present (or when you force it with --browser).

Interactive SSO login

# Sign in with the browser (used automatically when no API key is configured):
$ revenexx login

# Force SSO even if an API key is present (alias: --sso):
$ revenexx login --browser

This opens your browser to sign in with Zitadel, captures the response on a local loopback callback (a fixed port — 8000 by default; free it if login reports it's in use), exchanges it for a JWT, and stores the JWT (plus a refresh token) in ~/.revenexx/prefs.json. Expired JWTs are refreshed automatically; if the refresh fails you're prompted to login again. Once signed in, commands authenticate with the JWT in the Authorization: Bearer header.

The Zitadel application is preconfigured, but every value can be overridden through the environment — useful for self-hosted or staging identity providers:

| Variable | Default | Purpose | |---|---|---| | REVENEXX_SSO_ISSUER | https://id.revenexx.com | OIDC issuer; the authorize/token/userinfo endpoints come from its discovery document | | REVENEXX_SSO_CLIENT_ID | built-in CLI client | Zitadel application (native / public) client ID | | REVENEXX_SSO_REDIRECT_URI | http://127.0.0.1:8000/callback | Loopback callback — must exactly match a redirect URI registered on the Zitadel app |

API key login (non-interactive)

# CI / scripts:
$ revenexx login --token <token> --tenant <tenant>

# Project workspace — drop credentials in `.env` or `.revenexx.yaml`:
$ revenexx login

With no flags, login resolves a token from (in order) --token, REVENEXX_API_KEY, then .revenexx.yaml. A found token is validated against the gateway (GET /locale) and persisted to ~/.revenexx/prefs.json.

Inspecting and clearing your session

$ revenexx whoami   # auth method, its source, tenant and endpoint
$ revenexx logout    # clears the stored local session(s)

whoami reports where the active credential comes from — e.g. REVENEXX_API_KEY env var, .revenexx.yaml, or login session. Note that logout only clears the stored session: a key supplied via REVENEXX_API_KEY or .revenexx.yaml keeps authenticating you (and outranks any SSO session), so logout will warn you when one is still active. Unset it to fully sign out.

Credential resolution order

For any command that needs auth, credentials are resolved as:

1. CLI flag — --token, --endpoint, --project-id, --tenant
2. Environment variables — REVENEXX_API_KEY, REVENEXX_API_URL, REVENEXX_TENANT (legacy alias REVENEXX_PROJECT is still honoured)
3. Project file .revenexx.yaml — nearest one, walking up from the current directory
4. Global config at ~/.revenexx/prefs.json — an API key, or an SSO JWT, populated by revenexx login
5. Built-in default endpoint

When no API key resolves, a stored SSO JWT (from login --browser) is used instead, sent in the Authorization: Bearer header.

Exception: the tenant slug prefers the explicit tenants use switch — --tenant flag → ~/.revenexx/tenant → REVENEXX_TENANT → .revenexx.yaml.

Versioning & changesets

The CLI uses Changesets for reviewable version bumps. When you ship a user-visible change, add a changeset alongside your PR:

$ npx changeset

The CLI prompts for a semver bump (major / minor / patch) and a short summary, then writes the answer to .changeset/<random-name>.md. Commit that file with the rest of the PR — the entry shows up in the PR diff and is reviewable like any other change.

At release time, the publish workflow runs npx changeset version, which:

• bumps package.json,
• aggregates all pending .changeset/*.md into CHANGELOG.md,
• removes the consumed changesets.

The workflow then stamps the git-tag version (so v1.2.3 always ends up as 1.2.3 regardless of what changesets computed) and publishes to the npm registry.

See .changeset/README.md for a deeper walkthrough.

Clean-machine install verification

A throwaway-container smoke test for the install path lives at scripts/verify-install.sh. It boots a fresh node:20-bookworm-slim image, installs the CLI from the npm registry, and asserts revenexx -v / --help / login --help work.

# Verify the published npm build:
$ npm run verify:install

# Verify a local working copy (npm pack → install inside the container):
$ npm run verify:install:local

Use the --image flag on the script to pin a specific Node base (e.g. --image node:22-alpine).

Tenants

revenexx tenants scopes follow-up commands to a specific Revenexx tenant.

| Command | Status | |---|---| | revenexx tenants use <slug> | ✅ Persists the active slug to ~/.revenexx/tenant (overriding REVENEXX_TENANT). When an API key is available the slug is validated against the gateway first; a tenant the key can't access is rejected unless --force is passed. | | revenexx tenants current | ✅ Prints the active slug. Pass --check to verify it against the gateway. | | revenexx tenants list | ✅ Lists every tenant known to this machine (flag, env, .revenexx.yaml, ~/.revenexx/tenant, login sessions) with its sources and whether the current API key can access it. The gateway doesn't expose a /v1/tenants endpoint (and by design never discloses whether a tenant exists), so this is a client-side aggregate verified per-slug. |

Command aliases

Type less. The CLI resolves both built-in abbreviations and your own user-defined aliases before running a command — git-style — so revenexx p ls reaches revenexx products list. A real command always wins over an alias of the same name, and a built-in alias is a no-op when its target service isn't part of this SDK.

Built-in abbreviations

| Kind | Examples | |---|---| | Services (first token) | p/prod → products, o/ord → orders, cust → customers, cat → categories, inv → inventories, pay → payments, ship → shipping, msg → messaging | | Verbs (second token) | ls/l → list, g → get, mk/new/add → create, up/upd/edit → update, rm/del/d → delete |

Run revenexx alias list to see the full built-in table.

User-defined aliases

Persisted in ~/.revenexx/prefs.json and shared across all sessions on the machine.

# Create / update an alias (quote multi-word expansions):
$ revenexx alias set deploy "apps create-deployment --activate true"
$ revenexx deploy            # runs the expansion above

# List and remove:
$ revenexx alias list
$ revenexx alias remove deploy

Production safety banner

Before most commands, the CLI prints a one-line banner to stderr showing which tenant and endpoint you're about to hit. When the context is production the banner turns into a prominent red PRODUCTION badge — the single best guard against "I ran that against prod". It is suppressed automatically for context-free commands such as status, alias, and repl.

 PRODUCTION  acme → api.revenexx.com          # prod / sensitive
● staging → staging.revenexx.internal          # everything else (dim)

A context is treated as production when any of these hold:

• the endpoint is the built-in default (the live production gateway),
• the endpoint or tenant slug contains prod, or
• the tenant is in your configured sensitive list.

Configure the sensitive list (comma-separated, empty string clears it) or point at it from the environment:

$ revenexx client --sensitive-tenants "acme,globex"
$ REVENEXX_SENSITIVE_TENANTS="acme,globex" revenexx products list

Because it's on stderr the banner never contaminates --json output, and it's suppressed automatically for --json, non-interactive (piped) runs, and when you pass -q / --quiet.

status

A one-glance health/identity panel — richer than whoami. Shows the signed-in user, active tenant and endpoint, auth method, the SSO token expiry countdown, and a live gateway health probe (with a short timeout so it never hangs offline).

$ revenexx status
User          : [email protected]
Auth method   : SSO (Zitadel)
Tenant        : acme
Endpoint      : https://api.revenexx.com
Token expires : in 2h 41m
Gateway       : ok (v1.4.0)

Add --json for a machine-readable object.

Interactive shell (repl)

revenexx repl opens an authenticated interactive shell so you can run several commands without re-typing revenexx or re-resolving auth each time. It reuses the same command tree as the CLI, so everything — including built-in and user-defined aliases — works identically.

$ revenexx repl
ℹ Interactive shell — type a command, help, or exit. Tab completes command names.
revenexx> products list
revenexx> p get --product-id abc123
revenexx> help
revenexx> exit

• Tab completes top-level command names, then a service's subcommands.
• help (or ?) prints the command list; exit (or quit, q, Ctrl-D) leaves the shell.
• Missing required options prompt interactively just like they do outside the shell (search/select), so p get will ask for the product id. Ctrl-C cancels the current line without leaving the shell.
• The production safety banner is shown before every command in the session (prominent and red for production) — the safeguard matters most in a rapid-fire shell. Launch with revenexx --quiet repl to silence it for the session.

Full-screen app (tui)

revenexx tui — or just a bare revenexx on a terminal, since this is the default landing experience — opens a full-screen terminal app for the whole CLI: browse the command tree in a sidebar, fill in a command's parameters with a guided form, and read the results in a scrollable table — all on one screen that always shows the tenant and endpoint you're hitting. It's built on the same command tree as the rest of the CLI, so every service command, plugin, and alias is reachable, and each action maps to a plain one-shot command you can copy out and script.

$ revenexx         # bare invocation on a TTY → launches the TUI
$ revenexx tui     # explicit, always works

• Needs an interactive terminal (a TTY); in a pipe or CI it exits with a hint to use one-shot commands.
• Launched by default from a bare revenexx on a TTY. Set REVENEXX_NO_TUI=1 or defaultMode: guided|help in .revenexx.yaml to opt out (see Three ways to use it); revenexx tui always launches it explicitly.
• Browse: ↑/↓ move, Enter/→ open a group or run a command, Esc/← go back (Esc quits at the top level), q back/quit. Type or press / to filter.
• Themes: press ^t for a live theme picker — arrow through the list to preview the whole UI instantly, Enter keeps it, Esc reverts. The choice is saved to prefs.json and restored next launch. Start with a specific one via revenexx tui --theme <name> or the REVENEXX_THEME env var. Built-in: revenexx (default), dark, light, dracula, nord, solarized-dark, solarized-light, gruvbox, monokai, one-dark, matrix. On terminals that honour it (e.g. Ghostty) the theme also sets the terminal background.
• Run: commands with required parameters open a form; destructive ones ask to confirm (y/n); the rest run immediately. The detail pane shows the equivalent one-shot command.
• Forms: Tab/Shift+Tab move between fields, ←/→/Space cycle toggles and choices, Enter advances or runs, ^r runs from any field. Values are validated on submit; secrets (password/token/api-key) are masked. Resource-id fields open the matching list as a filterable table — type to narrow it (server-side when the endpoint supports search, otherwise across the loaded rows), ↑/↓ to move, Enter to pick the highlighted record's id.
• JSON body fields: an object parameter (e.g. --data) opens a full-screen key/value editor — Enter adds a field (or appends an array item), Tab switches between the key and value cell, ^d deletes the focused field, ^s saves it back to the form. Values are entered as JSON ("text", 42, true) and validated live, so the request body round-trips exactly. Nested JSON is edited in place: a value that is an object or array shows as { n fields } / [ n items ], and → drills into it one level deeper (breadcrumb data › meta › [0], any depth); Esc goes back up a level (and cancels at the top). Type {} or [] into a value to start a nested container.
• Results: table with ↑/↓ rows, Enter for row detail, / to filter the loaded rows (type to narrow across all columns, Esc clears), ←/→ to scroll columns, n/p to page, o to cycle output format (table/json/jsonl/csv), y to copy (Y copies the whole output), c to open the matching create form, u to open the matching update pre-filled, d to delete the record (behind the confirm modal), e to edit parameters. u/d act on the row under the cursor in a list, or on the single record from a get; c needs no row, so it works from an empty list too.
• The header carries a persistent, filled yellow ▲ PRODUCTION chip (the same production safety signal) for the whole session.
• Not browsable in the TUI (still available as one-shot commands): tui, repl, update, generate, types, completion.

Global Configuration

The CLI stores its state in ~/.revenexx/prefs.json. It holds one entry per signed-in session, keyed by a generated session ID, plus a top-level current that points at the active one. You don't normally edit this by hand — it's written by login, logout, tenants use, and client.

{
    "current": "6a3ba27f0010bb19c8e6",
    "6a3ba27f0010bb19c8e6": {
        "endpoint": "https://api.revenexx.com",
        "email": "[email protected]",
        "authMethod": "sso",
        "jwt": "<json-web-token>",
        "refreshToken": "<refresh-token>",
        "jwtExpiresAt": 1782336318182
    }
}

| Key | Scope | Description | |-----|-------|-------------| | current | top-level | ID of the active session (set on login, cleared on logout) | | authMethod | session | apikey or sso | | endpoint | session | Revenexx API URL for the session | | email | session | Signed-in identity (or apikey:<tenant> for API-key sessions) | | key | session | Gateway API key — API-key sessions; sent as X-Revenexx-Api-Key | | jwt | session | SSO JSON Web Token — sent as Authorization: Bearer | | refreshToken | session | SSO refresh token, used to silently renew the JWT | | jwtExpiresAt | session | JWT expiry (epoch ms); the CLI refreshes shortly before it lapses | | selfSigned | session | Allow self-signed TLS certificates (true/false) |

Rather than editing the file, configure the active session via the CLI:

$ revenexx client --endpoint https://api.revenexx.com
$ revenexx client --key YOUR_API_KEY
$ revenexx client --self-signed true

Scripting & automation

The CLI is built to drop into shell scripts and CI pipelines.

Output formats

Pick a renderer with -o, --output <format>:

| Format | Use | |--------|-----| | table (default) | Human-readable, aligned columns; adapts to the terminal width. | | json | Byte-stable, uncolored JSON for piping to jq etc. --json (-j) is a shorthand. | | jsonl (ndjson) | NDJSON / JSON Lines — one compact record per line, ideal for streaming large lists into jq -c, xargs, or log pipelines. --jsonl is a shorthand. | | csv | RFC 4180 rows — a header line plus one line per record. --csv is a shorthand. | | yaml | Losslessly structured YAML. --yaml is a shorthand. | | markdown (md) | GitHub-flavored Markdown table — handy for docs, PR comments, and issues. --markdown / --md are shorthands. |

Narrow the columns/fields with --fields. On a list response it projects the columns of the returned collection; on a single record it keeps just those keys:

$ revenexx <service> list -o csv --fields id,name,createdAt
$ revenexx <service> get <id> -o json --fields id,status | jq .status

On a terminal, all formats prompt for any missing required option; when the output is piped (non-TTY) the command fails fast instead of hanging — so automation never blocks on a prompt.

Machine-readable errors & exit codes

Under --json/-o json or --quiet, failures are written to stderr as { "error": { "message", "code", "type", "requestId" } } and the process exits with a meaningful code so scripts can branch on why a command failed:

| Exit code | Meaning | |-----------|---------| | 0 | Success | | 2 | Usage error (bad flags/arguments) | | 4 | Authentication/authorization failure (401/403) | | 5 | Not found (404) | | 8 | Rate limited (429) | | 1 | Generic failure (network, timeout, 5xx, …) |

--quiet opts into structured errors and exit codes without committing to a specific stdout format — useful when you only care about success/failure, or want to pair it with a non-JSON renderer.

if ! revenexx --quiet <service> get "$id" > /dev/null; then
  case $? in
    4) echo "not authenticated"  ;;
    5) echo "no such resource"   ;;
    8) echo "rate limited — back off and retry" ;;
    *) echo "request failed"     ;;
  esac
fi

Request bodies from a file or stdin

Create/update commands accept a JSON body inline, from a file (@path), or from stdin (-) via --data, so you can round-trip resources:

$ revenexx <service> get <id> -o json > body.json
# edit body.json ...
$ revenexx <service> update <id> --data @body.json

# or straight through a pipe
$ cat body.json | revenexx <service> create --data -

Explicit flags (e.g. --name) override matching keys from --data.

Putting it together

# Stream a large list one record per line straight into jq
$ revenexx <service> list --jsonl | jq -r 'select(.status == "active") | .id'

# Edit-in-place round-trip
$ revenexx <service> get "$id" -o json > item.json
$ jq '.name = "Renamed"' item.json | revenexx <service> update "$id" --data -

# Drop a Markdown table into a PR comment or report
$ revenexx <service> list --md --fields id,name,status >> report.md

Sample

See a runnable example for this SDK in the samples repo.

Contribution

This library is auto-generated by the Revenexx SDK Generator. To learn more about how you can help us improve this SDK, please check the contribution guide before sending a pull-request.

To build and test the CLI for development, follow these steps

1. Clone the CLI repository and install dependencies

$ git clone https://github.com/revenexx-sdks/cli
$ cd cli
$ bun install

2. Build the CLI

$ npm run build

3. Install the CLI globally from the local build

$ npm install -g .

4. You can now use the CLI

$ revenexx -v

License

Please see the license file for more information.