@revenexx/cli 0.0.7 → 0.0.9

package/README.md

@@ -1,6 +1,6 @@
 > **This repository is auto-generated by the [Revenexx SDK Generator](https://github.com/revenexx/sdk-generator). Do not submit changes directly — they will be overwritten on the next generation run.**
 
-# Revenexx API — revenexx Revenexx CLI SDK
+# Revenexx CLI SDK
 
 ![License](https://img.shields.io/github/license/revenexx-sdks/cli.svg?style=flat-square)
 ![Version](https://img.shields.io/badge/api%20version-1.0.0-blue.svg?style=flat-square)
@@ -9,11 +9,11 @@
 
 Revenexx command-line interface for managing your platform.
 
-![Revenexx API — revenexx](https://revenexx.com/images/logo.svg)
+![Revenexx](https://revenexx.com/images/logo.svg)
 
 ## Installation
 
-The Revenexx API — revenexx CLI is a Node based command line tool to help you interact with the Revenexx API — revenexx API. The CLI is distributed both as an [`npm package`](https://www.npmjs.com/package/@revenexx/cli) as well as [pre built binaries](https://github.com/revenexx-sdks/cli/releases/latest) for specific operating systems and architectures.
+The Revenexx CLI is a Node based command line tool to help you interact with the Revenexx API. The CLI is distributed both as an [`npm package`](https://www.npmjs.com/package/@revenexx/cli) as well as [pre built binaries](https://github.com/revenexx-sdks/cli/releases/latest) for specific operating systems and architectures.
 
 ### Install using NPM
 ---
@@ -28,7 +28,7 @@ Once the installation is complete, you can verify the install using
 
 ```sh
 $ revenexx -v
-0.0.7
+0.0.9
 ```
 
 ### Install using prebuilt binaries
@@ -62,115 +62,114 @@ $ scoop install https://raw.githubusercontent.com/revenexx-sdks/cli/master/scoop
 Once the installation completes, you can verify your install using
 ```
 $ revenexx -v
-0.0.7
+0.0.9
 ```
 
 ## Getting Started
 
-Before you can use the CLI, you need to login to your Revenexx account.
+### 1. Sign in
+
+Authenticate once — the CLI stores your session under `~/.revenexx/`.
 
 ```sh
+# Developers: interactive SSO sign-in via the browser (Zitadel)
 $ revenexx login
 
-? Enter your email test@test.com
-? Enter your password ********
-✓ Success 
+# CI / scripts: a gateway API key
+$ revenexx login --token <token> --tenant <tenant>
 ```
-This will also prompt you to enter your Revenexx endpoint ( default: https://revenexx.com/v1 )
 
-* ### Initialising your project
-Once logged in, the CLI needs to be initialised before you can use it with your Revenexx project. You can do this with the `revenexx init project` command.
+Confirm who you're signed in as at any time:
 
 ```sh
-$ revenexx init project
+$ revenexx whoami
 ```
 
-The following prompt will guide you through the setup process. The `init` command also creates a `revenexx.json` file representing your Revenexx project.
+See the [Authentication](#authentication) section below for the full login, credential-resolution, and sign-out details.
 
-The `revenexx.json` file does a lot of things.
-* Provides context to the CLI
-* Keeps track of all your cloud functions
-* Keeps track of all your project's collections
-* Helps you deploy your Revenexx project to production and more..
+### 2. Choose a tenant
+
+Every request is scoped to a tenant. Set the active one once and the CLI remembers it:
 
-You can also fetch all the collections in your current project using
 ```sh
-revenexx init collection
+$ revenexx tenants use <slug>
+$ revenexx tenants current
 ```
 
-* ### Creating and deploying cloud functions
+### 3. Run a command
 
-The CLI makes it extremely easy to create and deploy Revenexx's cloud functions. Initialise your new function using
+Each API service is exposed as a command, and every method as a subcommand. Discover them with `--help`:
 
-```
-$ revenexx init function
-? What would you like to name your function? My Awesome Function
-? What runtime would you like to use? Node.js (node-15.5)
-✓ Success 
+```sh
+$ revenexx --help                      # list every service
+$ revenexx <service> --help            # list a service's methods
+$ revenexx <service> <method> --help   # show a method's flags
 ```
 
-This will create a new function `My Awesome Function` in your current Revenexx project and also create a template function for you to get started.
+For example, to list products:
 
 ```sh
-$ tree My\ Awesome\ Function 
-
-My Awesome Function
-├── README.md
-├── index.js
-├── package-lock.json
-└── package.json
-
-0 directories, 4 files
+$ revenexx products products-list
 ```
 
-You can now deploy this function using
+Ready-to-copy examples for every command are generated under [`docs/examples/`](docs/examples).
 
-```sh
-$ revenexx push function
+> ### 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
+> ```sh
+> $ revenexx client --self-signed true
+> ```
 
-? Which functions would you like to deploy? My Awesome Function (61d1a4c81dfcd95bc834)
-ℹ Info Deploying function My Awesome Function ( 61d1a4c81dfcd95bc834 )
-✓ Success Deployed My Awesome Function ( 61d1a4c81dfcd95bc834 )
-```
+## Authentication
 
-Your function has now been deployed on your Revenexx server! As soon as the build process is finished, you can start executing the function.
+The CLI supports two ways to authenticate:
 
-* ### Deploying Collections
+- **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.
 
-Similarly, you can deploy all your collections to your Revenexx server using
+An API key always takes precedence; SSO is the fallback when no key is present (or when you force it with `--browser`).
 
-```sh
-revenexx push collection
-```
+### Interactive SSO login
 
-> ### Note
-> By default, requests to domains with self signed SSL certificates (or no certificates) are disabled. If you trust the domain, you can bypass the certificate validation using
 ```sh
-$ revenexx client --selfSigned true
+# 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
 ```
 
-## Authentication
+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:
 
-The CLI is token-based. There is no email/password flow — every session uses a gateway API key.
+| 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 |
 
-### Default (non-interactive)
+### API key login (non-interactive)
 
 ```sh
+# 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`. If a token is found, it's validated against the gateway (`GET /locale`) and persisted to `~/.revenexx/prefs.json`. If no token is found, the command errors out and tells you how to supply one.
+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`.
 
-Typical setups:
+### Inspecting and clearing your session
 
 ```sh
-# CI / scripts
-$ revenexx login --token <token> --tenant <tenant>
-
-# Project workspace — drop credentials in `.env` or `.revenexx.yaml`
-$ revenexx login
+$ 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:
@@ -178,9 +177,11 @@ 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` — populated by `revenexx login`
+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
@@ -229,31 +230,35 @@ Use the `--image` flag on the script to pin a specific Node base (e.g. `--image
 
 ## Global Configuration
 
-The CLI stores its configuration in `~/.revenexx/prefs.json`. You can seed this file manually before running any commands:
+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`.
 
 ```json
 {
-    "current": "",
-    "endpoint": "https://api.revenexx.com",
-    "selfSigned": false,
-    "project": "",
-    "key": "",
-    "locale": "en-US",
-    "mode": "default"
+    "current": "6a3ba27f0010bb19c8e6",
+    "6a3ba27f0010bb19c8e6": {
+        "endpoint": "https://api.revenexx.com",
+        "email": "you@example.com",
+        "authMethod": "sso",
+        "jwt": "<json-web-token>",
+        "refreshToken": "<refresh-token>",
+        "jwtExpiresAt": 1782336318182
+    }
 }
 ```
 
-| Key | Description |
-|-----|-------------|
-| `current` | Active session ID (set automatically on login) |
-| `endpoint` | Your Revenexx API — revenexx server URL |
-| `selfSigned` | Allow self-signed TLS certificates (`true`/`false`) |
-| `project` | Default project ID |
-| `key` | API key for server-side access |
-| `locale` | Locale for API responses |
-| `mode` | Auth mode — `default` (API key) or `admin` (cookie session) |
+| 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`) |
 
-You can also configure these values via the CLI:
+Rather than editing the file, configure the active session via the CLI:
 
 ```sh
 $ revenexx client --endpoint https://api.revenexx.com
@@ -261,9 +266,13 @@ $ revenexx client --key YOUR_API_KEY
 $ revenexx client --self-signed true
 ```
 
+## Sample
+
+See a runnable example for this SDK in the [samples repo](https://github.com/revenexx-sdks/samples/tree/main/cli).
+
 ## Contribution
 
-This library is auto-generated by RevenexxAPIRevenexx custom [SDK Generator](https://github.com/revenexx api — revenexx/sdk-generator). To learn more about how you can help us improve this SDK, please check the [contribution guide](https://github.com/revenexx api — revenexx/sdk-generator/blob/master/CONTRIBUTING.md) before sending a pull-request.
+This library is auto-generated by the Revenexx [SDK Generator](https://github.com/revenexx/sdk-generator). To learn more about how you can help us improve this SDK, please check the [contribution guide](https://github.com/revenexx/sdk-generator/blob/master/CONTRIBUTING.md) before sending a pull-request.
 
 To build and test the CLI for development, follow these steps