@faable/faable 2.2.0 → 3.1.0

package/README.md

@@ -9,67 +9,105 @@
   Your React, Node.js or Python apps, up to the cloud in seconds.
 </p>
 
-## Faable
+## Faable CLI
 
-Faable is the best platform to build modern architectures that scale precisely
-to meet demand. We handle the hard stuff so you can focus on building cloud
-ready apps. Make your business cloud driven and join those awesome companies.
+`@faable/faable` is the command-line interface for the Faable platform. It covers
+**Faable Deploy** (ship and operate apps) and **Faable Auth** (manage an identity
+tenant: users, login-flow actions, OAuth clients and the audit log) from one binary.
 
-To install the latest version of Faable CLI:
+Full reference: **[faable.com/docs/cli](https://faable.com/docs/cli)**.
+
+To install the latest version:
 
 ```bash
 npm i -g @faable/faable
 ```
 
-## Runtimes
+## Commands
 
-`faable deploy` auto-detects the runtime from the files in your project (no
-config needed in the common case):
+| Group | What it does | Docs |
+| --- | --- | --- |
+| `faable login` / `whoami` / `logout` | Session management (device flow; CI uses OIDC, no login needed) | [Authentication](https://faable.com/docs/cli#authentication) |
+| `faable deploy` | `launch` (the default: a bare `faable deploy` deploys the current directory), then `status`, `logs`, `deployments`, `inspect`, `trigger`, `redeploy`, `cancel`, `open`, `list` | [Deployment](https://faable.com/docs/cli#deployment) |
+| `faable deploy secrets` | Environment variables: `list`, `set` (`KEY=VALUE` or `--env-file`), `rm` | [Secrets](https://faable.com/docs/cli#secrets) |
+| `faable deploy domains` | Custom domains: `add` (prints the CNAME), `list`, `check`, `rm` | [Domains](https://faable.com/docs/cli#domains) |
+| `faable deploy waf` | Edge rules: `block` (403), `sink` (404 without waking the app), `list`, `rm` | [Edge rules](https://faable.com/docs/cli#edge-rules-waf) |
+| `faable auth users` | `list` (FaableQL filters), `get` (federated identities included), `suspend`, `reinstate` | [Users](https://faable.com/docs/cli#users) |
+| `faable auth actions` | Login-flow hooks: `list`, `get --code`, `create`, `update`, `rm` | [Actions](https://faable.com/docs/cli#actions) |
+| `faable auth clients` | OAuth clients: `list`, `get --secret`, `create`, `rm` | [OAuth clients](https://faable.com/docs/cli#oauth-clients) |
+| `faable auth logs` | Audit log (read-only): `list` with filters, `get` | [Audit logs](https://faable.com/docs/cli#audit-logs) |
+
+Every command has `--help`; read commands accept `--json` for output you can pipe
+to `jq`. The complete table is in the
+[command reference](https://faable.com/docs/cli#command-reference).
+
+### Deploy
 
-| Detected by | Runtime |
-| --- | --- |
-| `package.json` | Node.js (Next.js, Vite, Astro, Gatsby, CRA, Vue, Angular, …) |
-| `requirements.txt` / `pyproject.toml` / `Pipfile` | Python |
-| `Dockerfile` | Your own image (any language) |
+```bash
+faable login
+faable deploy                       # deploy the current directory (= deploy launch)
+faable deploy launch --app app_x    # deploy another app, from anywhere
+faable deploy status                # phase, URL and detected stack
+faable deploy logs --build          # build output (--follow to tail)
+faable deploy secrets set KEY=value
+faable deploy domains add app.example.com
+```
 
-> A project with a `package.json` is always treated as Node. To deploy a Python
-> backend that also has a `package.json`, ship a `Dockerfile` instead.
+### Faable Auth
 
-### Node.js / static frameworks
+`faable auth` manages a [Faable Auth](https://faable.com/docs/auth) tenant and
+reuses your `faable login` session. Point it at your tenant with
+`--auth-url https://<account>.auth.faable.link` (or `FAABLE_AUTH_URL`).
 
-SPA frameworks are built and served automatically. If the project has **no
-`start` script**, the built output is served statically (e.g. Vite → `npx vite
-preview`, CRA/Vue/Angular → `serve`). If it defines a `start` script (custom SSR,
-Next.js, Nuxt, Remix, …), that command is used.
+```bash
+faable auth users list --query email_verified:false --limit 50
+faable auth users get user_abc123                   # includes GitHub/… identities
+faable auth users suspend user_abc123 -r "abuse: crypto miner"
 
-### Python
+# Bulk: pipe ids from a filtered listing
+faable auth users list --suspended --json | jq -r '.[].id' | faable auth users reinstate -y
 
-The start command is detected from your framework:
+faable auth actions create -n add-claims -t post-login -f ./claims.js
+faable auth clients create -n my-app --callback https://app.example.com/callback
+faable auth logs list --origin oauth --status failed --since 2026-08-01
+```
 
-| Framework | Detected from | Start command |
-| --- | --- | --- |
-| Django | `manage.py` + the package with `wsgi.py` | `gunicorn <pkg>.wsgi:application` |
-| FastAPI / ASGI | `fastapi`/`uvicorn`/`starlette` dep | `uvicorn <module>:app` |
-| Flask | `flask` dep | `gunicorn <module>:app` |
+See [`faable auth` in the docs](https://faable.com/docs/cli#faable-auth) for
+every flag. The concepts behind each group are documented in Faable Auth:
+[users & suspension](https://faable.com/docs/auth/suspend-users),
+[actions](https://faable.com/docs/auth/extensibility/actions),
+[login flows](https://faable.com/docs/auth/login-flows),
+[OAuth clients](https://faable.com/docs/auth/clients) and
+[audit logs](https://faable.com/docs/auth/logs).
 
-Dependencies are installed inside the image from `requirements.txt`,
-`pyproject.toml` or `Pipfile`. `gunicorn`/`uvicorn` are installed automatically
-if missing.
+## Documentation
 
-Pin the Python version with a `runtime.txt` (`python-3.11.3`), a
-`.python-version`, or `requires-python` in `pyproject.toml`.
+The CLI is a thin client: what it deploys and what it manages is documented in
+the public docs, not here.
 
-### Overriding detection
+### CLI
 
-When auto-detection doesn't fit, set the commands explicitly:
+- [Command reference](https://faable.com/docs/cli#command-reference) — every command and flag
+- [Authentication](https://faable.com/docs/cli#authentication) — `login`, `whoami`, `logout`
+- [Deployment](https://faable.com/docs/cli#deployment) · [Inspecting](https://faable.com/docs/cli#inspecting) · [Secrets](https://faable.com/docs/cli#secrets) · [Domains](https://faable.com/docs/cli#domains) · [Edge rules](https://faable.com/docs/cli#edge-rules-waf) · [Faable Auth](https://faable.com/docs/cli#faable-auth)
 
-- `faable.json` — `{ "buildCommand": "...", "startCommand": "..." }`
-- `Procfile` — a `web:` line, e.g. `web: gunicorn app:app --bind 0.0.0.0:$PORT`
+### Faable Deploy
 
-Precedence: `faable.json` → `Procfile` → auto-detection. The container listens on
-`$PORT` (80).
+- [Get started](https://faable.com/docs/deploy/get-started) — first deploy in minutes
+- [How deployment works](https://faable.com/docs/deploy/how-it-works) — push-to-deploy, builds and releases
+- [Runtime](https://faable.com/docs/deploy/runtime) — supported languages, framework detection, `faable.json` / `Procfile` overrides
+- [What the builder expects](https://faable.com/docs/deploy/build-requirements) — build and start commands, `$PORT`, monorepos
+- [Environment & releases](https://faable.com/docs/deploy/environment) — secrets, env vars and release versions
+- [Custom domains](https://faable.com/docs/deploy/domains/custom-domain) and [SSL certificates](https://faable.com/docs/deploy/domains/ssl-certificates)
+- [Web Application Firewall](https://faable.com/docs/deploy/security-waf) — the edge rules behind `faable deploy waf`
+- [Deploy from your own CI](https://faable.com/docs/deploy/github-actions) — OIDC, no login needed
+- Framework guides: [Next.js](https://faable.com/docs/deploy/guides/guide-next), [Vite](https://faable.com/docs/deploy/guides/guide-vite), [Astro](https://faable.com/docs/deploy/guides/guide-astro), [Express](https://faable.com/docs/deploy/guides/guide-express), [Django](https://faable.com/docs/deploy/guides/guide-django), [FastAPI](https://faable.com/docs/deploy/guides/guide-fastapi), [Flask](https://faable.com/docs/deploy/guides/guide-flask), [PHP](https://faable.com/docs/deploy/guides/guide-php)
 
-## Documentation
+### Faable Auth
 
-For details on how to use Faable CLI, check out our
-[documentation](https://faable.com/docs).
+- [Get started](https://faable.com/docs/auth/get-started) — create a tenant
+- [Clients](https://faable.com/docs/auth/clients) · [Connections](https://faable.com/docs/auth/connections) · [Social login](https://faable.com/docs/auth/social) · [Passwordless](https://faable.com/docs/auth/passwordless)
+- [Suspend users](https://faable.com/docs/auth/suspend-users) — what `users suspend` / `reinstate` do to sessions and tokens
+- [Login flows](https://faable.com/docs/auth/login-flows) and [actions](https://faable.com/docs/auth/extensibility/actions) — the hooks managed by `auth actions`
+- [Logs](https://faable.com/docs/auth/logs) — the audit trail read by `auth logs`
+- [OAuth 2.0 flows](https://faable.com/docs/auth/oauth-flows) · [OpenID Connect](https://faable.com/docs/auth/oidc) · [Validate access tokens](https://faable.com/docs/auth/validate-access-tokens)

package/dist/api/context.js

@@ -20,7 +20,7 @@ const context = async (targetAppId) => {
         try {
             const idToken = process.env.FAABLE_ID_TOKEN || (await getIDToken("https://faable.com"));
             // targetAppId disambiguates a monorepo (several apps, one repo) in the
-            // OIDC exchange — from `faable deploy <app_id>`.
+            // OIDC exchange — from `faable deploy --app <app_id>`.
             api = FaableApi.create({
                 authStrategy: oidc_strategy,
                 auth: { idToken, appId: targetAppId },

package/dist/api/strategies/oidc.strategy.js

@@ -27,7 +27,7 @@ const exchangeGithubOidcToken = async (gh_token, target_app_id) => {
             // Monorepo: several apps are linked to the same repository.
             if (status === 400) {
                 throw new Error(serverMessage ||
-                    "This repository has multiple linked apps. Specify which one with `faable deploy <app_id>`.", { cause: err });
+                    "This repository has multiple linked apps. Specify which one with `faable deploy --app <app_id>`.", { cause: err });
             }
             throw new Error(`Faable OIDC token exchange failed (${status ?? "network error"})${serverMessage ? `: ${serverMessage}` : ""}`, { cause: err });
         }

package/dist/commands/deploy/help.js

@@ -0,0 +1,17 @@
+import { log } from '../../log.js';
+
+// `faable deploy` with nothing to deploy has to show what `deploy` CAN do —
+// the same way `faable auth` lists its subcommands. yargs only hands the
+// parser to a builder, never to a handler, so the `deploy` builder parks its
+// level here for `launch` to print.
+let deploy_level = null;
+const capture_deploy_help = (yargs) => {
+    deploy_level = yargs;
+    return yargs;
+};
+const show_deploy_help = () => {
+    if (deploy_level)
+        deploy_level.showHelp(help => log.info(help));
+};
+
+export { capture_deploy_help, show_deploy_help };

package/dist/commands/deploy/index.js

@@ -1,10 +1,6 @@
-import prompts from 'prompts';
-import { requireApi } from '../../api/context.js';
-import { Configuration } from '../../lib/Configuration.js';
-import { log } from '../../log.js';
 import { link } from '../link/index.js';
 import { domains } from './domains/index.js';
-import { git_context } from './git_context.js';
+import { capture_deploy_help } from './help.js';
 import { cancel } from './inspect/cancel.js';
 import { deployments } from './inspect/deployments.js';
 import { inspect } from './inspect/inspect.js';
@@ -14,198 +10,46 @@ import { open_app } from './inspect/open.js';
 import { redeploy } from './inspect/redeploy.js';
 import { status } from './inspect/status.js';
 import { trigger } from './inspect/trigger.js';
-import { propose_release } from './release_version.js';
-import { deploy_remote } from './remote/index.js';
-import { resolve_app_id } from './resolve_app_id.js';
+import { launch } from './launch.js';
 import { secrets } from './secrets/index.js';
-import { is_superseded } from './superseded.js';
 import { waf } from './waf/index.js';
 
+// `faable deploy` — the deploy product. A command group and nothing else: it
+// holds no handler of its own, so every verb is a subcommand and the
+// hierarchy has no exception to remember. Deploying is `launch`, registered
+// as the group's default ($0) so `faable deploy` on its own still deploys the
+// current directory — the shortcut is an alias, not a second code path.
+//
+// The group deliberately has no positional. An app id typed where a
+// subcommand belongs (`faable deploy app_xxx secrets list`) used to be
+// swallowed by an `[app_id]` positional and silently DEPLOYED instead of
+// running the subcommand; .strictCommands() in src/index.ts now rejects it as
+// an unknown command. Another app is targeted with --app on `launch` and on
+// every subcommand alike.
 const deploy = {
-    command: 'deploy [app_id]',
+    command: 'deploy',
     // Name the subcommand groups so `faable --help` makes them discoverable
     // without digging into `faable deploy --help`.
     describe: 'Deploy a faable app and manage it (secrets, domains, logs, deployments…)',
-    builder: yargs => {
-        // Product subcommands live under `deploy` (yargs matches them before the
-        // app_id positional, so `faable deploy <app_id>` keeps working).
-        return yargs
-            .command(secrets)
-            .command(domains)
-            .command(waf)
-            .command(logs)
-            .command(status)
-            .command(apps_list)
-            .command(deployments)
-            .command(inspect)
-            .command(open_app)
-            .command(trigger)
-            .command(redeploy)
-            .command(cancel)
-            .command(link)
-            .positional('app_id', {
-            type: 'string',
-            description: 'App Identifier'
-        })
-            .option('workdir', {
-            alias: 'w',
-            type: 'string',
-            description: 'Working directory'
-        })
-            .option('release', {
-            type: 'string',
-            description: 'Release version to record on the deployment (injected as FAABLE_RELEASE). Defaults to FAABLE_RELEASE env or the latest git tag'
-        })
-            .option('yes', {
-            alias: 'y',
-            type: 'boolean',
-            default: false,
-            description: 'Skip the confirmation prompt (only asked in interactive terminals — CI is unaffected)'
-        })
-            .showHelpOnFail(false);
-    },
-    handler: async (args) => {
-        const workdir = args.workdir || process.cwd();
-        // Pass the explicit app target to the OIDC exchange so a monorepo (several
-        // apps, one repo) can be disambiguated in CI.
-        const ctx = await requireApi(args.app_id);
-        const { api } = ctx;
-        const config = Configuration.instance().deployConfig();
-        const app_id = await resolve_app_id(args.app_id, ctx.appId, api, workdir);
-        const app = await api.getApp(app_id);
-        // Guard against the `faable deploy <app_id> <subcommand>` typo: yargs
-        // doesn't recognize an unmatched trailing token as the subcommand, so it
-        // silently falls through to THIS handler and deploys `workdir` instead.
-        // Only prompts in a real terminal — CI (non-TTY) keeps deploying
-        // unattended exactly as before, so existing pipelines need no changes.
-        if (!args.yes && process.stdout.isTTY) {
-            const { confirm } = await prompts({
-                type: 'toggle',
-                name: 'confirm',
-                message: `Deploy "${app.name}" (${app.id}) from ${workdir}?`,
-                initial: false,
-                active: 'yes',
-                inactive: 'no'
-            });
-            if (!confirm) {
-                log.info('Cancelled.');
-                return;
-            }
-        }
-        // Monorepo Root Directory — single precedence rule everywhere
-        // (arch/deploy/root-dir-faable-json.md): App.root_dir (platform
-        // override, exceptional) > repo faable.json rootDir (the supported
-        // user option) > repo root. Matches the remote builder.
-        if (app.root_dir) {
-            config.rootDir = app.root_dir;
-            log.info(`📁 Root directory: ${app.root_dir} (platform override)`);
-        }
-        else if (config.rootDir) {
-            log.info(`📁 Root directory: ${config.rootDir} (from faable.json)`);
-        }
-        // Capture the commit/ref/actor so the deployment records which commit
-        // it came from and who pushed it (env in CI, git fallback locally).
-        const git = await git_context({ workdir });
-        // Propose the release version (--release > FAABLE_RELEASE > git tag).
-        // Optional: when absent the platform injects no FAABLE_RELEASE and the
-        // app falls back to its own version source.
-        const proposed = await propose_release({ workdir, explicit: args.release });
-        if (proposed) {
-            log.info(`🏷️ Release: ${proposed.release} (from ${proposed.source})`);
-        }
-        // Remote build only (arch/deploy/remote-artifact-default-cutover.md): the
-        // CLI no longer builds — it uploads the source and the platform builds
-        // server-side (framework detection, buildpacks, artifact/image output all
-        // live in the builder). No Docker, no local fallback: a rejected admission
-        // (build_mode=local opt-out, or the global kill-switch off) or a build
-        // error throws and exits red.
-        log.info(`🚀 Deploying "${app.name}" (${app.id})`);
-        const deployment = await deploy_remote({
-            api,
-            app,
-            git,
-            release: proposed?.release,
-            workdir
-        });
-        const dashboard_url = `https://dashboard.faable.com/deploy/${app.team}/app/${app.id}`;
-        log.info(`Preparing to deploy in faable cloud · ${deployment.id}`);
-        log.info(`📊 View it in the dashboard -> ${dashboard_url}`);
-        // Wait (up to 5 minutes) for the deployment to be promoted (live)
-        const wait = (ms) => new Promise(resolve => setTimeout(resolve, ms));
-        const timeoutMs = 5 * 60 * 1000;
-        const intervalMs = 5000;
-        const start = Date.now();
-        log.info(`⏳ Waiting for deployment to be promoted...`);
-        let promoted = false;
-        let failure = null;
-        let superseded = null;
-        // The pointer at wait-start is the PREVIOUS deployment (older than ours)
-        // — only a pointer CHANGE to something that isn't us needs a look.
-        const initialActiveId = app.status?.deployment;
-        while (Date.now() - start < timeoutMs) {
-            await wait(intervalMs);
-            try {
-                const current = await api.getApp(app.id);
-                if (current.status?.deployment === deployment.id) {
-                    promoted = true;
-                    break;
-                }
-                // Superseded: the pointer moved to a deployment at least as new as
-                // ours (twin workflows on the same push, or a rapid follow-up
-                // deploy). It only moves forward — waiting longer can never succeed.
-                const activeId = current.status?.deployment;
-                if (activeId && activeId !== initialActiveId) {
-                    const active = await api.getDeployment(activeId).catch(() => null);
-                    if (active &&
-                        is_superseded(deployment, active)) {
-                        superseded = activeId;
-                        break;
-                    }
-                }
-                // Watch for a terminal runtime failure so we fail fast (and red)
-                // instead of timing out green. The controller marks a crash-looping
-                // deployment ERROR — with a reason (e.g. a missing module) — within
-                // ~1min, long before this 5min promotion timeout.
-                const dep = await api.getDeployment(deployment.id);
-                const phase = dep.status?.phase;
-                if (phase === 'ERROR' || phase === 'BUILD_ERROR') {
-                    failure = { phase, reason: dep.status?.reason };
-                    break;
-                }
-                // CANCELED: the platform superseded this build before it produced a
-                // runnable (a sibling deployment of the app won the promotion).
-                if (phase === 'CANCELED') {
-                    superseded = dep.status?.reason ?? 'canceled';
-                    break;
-                }
-            }
-            catch (_error) {
-                // Ignore transient errors while polling and keep waiting
-                log.debug(`Polling app status failed, retrying...`);
-            }
-        }
-        if (promoted) {
-            log.info(`🌍 Deployment promoted and live, visit: https://${app.url}`);
-        }
-        else if (superseded) {
-            // Not a failure: the app IS live, just on a sibling deployment (e.g.
-            // duplicated workflows firing on the same push). Green exit — there is
-            // nothing for the user to fix in THIS run.
-            log.warn(`⚠️ Deployment superseded — a newer deployment of this app was promoted (${superseded}). The app is live: https://${app.url}`);
-        }
-        else if (failure) {
-            // Fail the command (non-zero exit → red GitHub Action) and surface the
-            // reason the controller captured so the user sees WHY without digging.
-            log.error(`❌ Deployment failed (${failure.phase}).`);
-            if (failure.reason)
-                log.error(failure.reason);
-            log.error(`Check the logs in the dashboard -> ${dashboard_url}`);
-            throw new Error(`Deployment ${deployment.id} failed with phase ${failure.phase}`);
-        }
-        else {
-            log.warn(`⌛ Timed out after 5min waiting for promotion. The deployment is still rolling out, check the dashboard -> ${dashboard_url}`);
-        }
-    }
+    builder: yargs => capture_deploy_help(yargs
+        .command(launch)
+        .command(secrets)
+        .command(domains)
+        .command(waf)
+        .command(logs)
+        .command(status)
+        .command(apps_list)
+        .command(deployments)
+        .command(inspect)
+        .command(open_app)
+        .command(trigger)
+        .command(redeploy)
+        .command(cancel)
+        .command(link)
+        .showHelpOnFail(false)),
+    // Unreachable: `launch` is the default command, so yargs routes a bare
+    // `faable deploy` there before it ever gets here.
+    handler: () => { }
 };
 
 export { deploy };

package/dist/commands/deploy/launch.js

@@ -0,0 +1,194 @@
+import prompts from 'prompts';
+import { requireApi } from '../../api/context.js';
+import { Configuration } from '../../lib/Configuration.js';
+import { log } from '../../log.js';
+import { git_context } from './git_context.js';
+import { show_deploy_help } from './help.js';
+import { propose_release } from './release_version.js';
+import { deploy_remote } from './remote/index.js';
+import { find_app_id } from './resolve_app_id.js';
+import { is_superseded } from './superseded.js';
+
+// `faable deploy launch` — the deploy itself, and the default command of the
+// `deploy` group, so a bare `faable deploy` runs exactly this. Every verb
+// under `deploy` is a subcommand now, this one included: the hierarchy holds
+// with no special case, and nothing can fall through to a deploy by accident
+// (that is how `faable deploy <app_id> secrets list` used to deploy).
+const launch = {
+    command: ['launch', '$0'],
+    describe: 'Deploy the current directory (the default: `faable deploy`)',
+    builder: yargs => yargs
+        .option('app', {
+        alias: 'a',
+        type: 'string',
+        description: 'App Identifier (defaults to the app linked to this repository)'
+    })
+        .option('workdir', {
+        alias: 'w',
+        type: 'string',
+        description: 'Working directory'
+    })
+        .option('release', {
+        type: 'string',
+        description: 'Release version to record on the deployment (injected as FAABLE_RELEASE). Defaults to FAABLE_RELEASE env or the latest git tag'
+    })
+        .option('yes', {
+        alias: 'y',
+        type: 'boolean',
+        default: false,
+        description: 'Skip the confirmation prompt (only asked in interactive terminals — CI is unaffected)'
+    })
+        .example('$0 deploy', 'Deploy the app linked to the current directory')
+        .example('$0 deploy --app app_a1b2c3', 'Deploy another app (monorepo: several apps, one repo)')
+        .showHelpOnFail(false),
+    handler: async (args) => {
+        const workdir = args.workdir || process.cwd();
+        // Pass the explicit app target to the OIDC exchange so a monorepo (several
+        // apps, one repo) can be disambiguated in CI.
+        const ctx = await requireApi(args.app);
+        const { api } = ctx;
+        const config = Configuration.instance().deployConfig();
+        const app_id = await find_app_id(args.app, ctx.appId, api, workdir);
+        // Nothing to deploy from here. `faable deploy` is the entry point to the
+        // whole product, so an unlinked directory is a perfectly normal way to
+        // arrive: list what deploy can do (like `faable auth` does) instead of
+        // answering a bare `faable deploy` with an error and nothing else.
+        if (!app_id) {
+            show_deploy_help();
+            log.error(`❌ No app linked to ${workdir}. Connect a repository from the dashboard (or run "faable deploy link"), or target one with --app <app_id>.`);
+            process.exit(1);
+        }
+        const app = await api.getApp(app_id);
+        // Confirm which app/dir is about to go out. Only in a real terminal — CI
+        // (non-TTY) deploys unattended, so pipelines need no changes.
+        if (!args.yes && process.stdout.isTTY) {
+            const { confirm } = await prompts({
+                type: 'toggle',
+                name: 'confirm',
+                message: `Deploy "${app.name}" (${app.id}) from ${workdir}?`,
+                initial: false,
+                active: 'yes',
+                inactive: 'no'
+            });
+            if (!confirm) {
+                log.info('Cancelled.');
+                return;
+            }
+        }
+        // Monorepo Root Directory — single precedence rule everywhere
+        // (arch/deploy/root-dir-faable-json.md): App.root_dir (platform
+        // override, exceptional) > repo faable.json rootDir (the supported
+        // user option) > repo root. Matches the remote builder.
+        if (app.root_dir) {
+            config.rootDir = app.root_dir;
+            log.info(`📁 Root directory: ${app.root_dir} (platform override)`);
+        }
+        else if (config.rootDir) {
+            log.info(`📁 Root directory: ${config.rootDir} (from faable.json)`);
+        }
+        // Capture the commit/ref/actor so the deployment records which commit
+        // it came from and who pushed it (env in CI, git fallback locally).
+        const git = await git_context({ workdir });
+        // Propose the release version (--release > FAABLE_RELEASE > git tag).
+        // Optional: when absent the platform injects no FAABLE_RELEASE and the
+        // app falls back to its own version source.
+        const proposed = await propose_release({ workdir, explicit: args.release });
+        if (proposed) {
+            log.info(`🏷️ Release: ${proposed.release} (from ${proposed.source})`);
+        }
+        // Remote build only (arch/deploy/remote-artifact-default-cutover.md): the
+        // CLI no longer builds — it uploads the source and the platform builds
+        // server-side (framework detection, buildpacks, artifact/image output all
+        // live in the builder). No Docker, no local fallback: a rejected admission
+        // (build_mode=local opt-out, or the global kill-switch off) or a build
+        // error throws and exits red.
+        log.info(`🚀 Deploying "${app.name}" (${app.id})`);
+        const deployment = await deploy_remote({
+            api,
+            app,
+            git,
+            release: proposed?.release,
+            workdir
+        });
+        const dashboard_url = `https://dashboard.faable.com/deploy/${app.team}/app/${app.id}`;
+        log.info(`Preparing to deploy in faable cloud · ${deployment.id}`);
+        log.info(`📊 View it in the dashboard -> ${dashboard_url}`);
+        // Wait (up to 5 minutes) for the deployment to be promoted (live)
+        const wait = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+        const timeoutMs = 5 * 60 * 1000;
+        const intervalMs = 5000;
+        const start = Date.now();
+        log.info(`⏳ Waiting for deployment to be promoted...`);
+        let promoted = false;
+        let failure = null;
+        let superseded = null;
+        // The pointer at wait-start is the PREVIOUS deployment (older than ours)
+        // — only a pointer CHANGE to something that isn't us needs a look.
+        const initialActiveId = app.status?.deployment;
+        while (Date.now() - start < timeoutMs) {
+            await wait(intervalMs);
+            try {
+                const current = await api.getApp(app.id);
+                if (current.status?.deployment === deployment.id) {
+                    promoted = true;
+                    break;
+                }
+                // Superseded: the pointer moved to a deployment at least as new as
+                // ours (twin workflows on the same push, or a rapid follow-up
+                // deploy). It only moves forward — waiting longer can never succeed.
+                const activeId = current.status?.deployment;
+                if (activeId && activeId !== initialActiveId) {
+                    const active = await api.getDeployment(activeId).catch(() => null);
+                    if (active &&
+                        is_superseded(deployment, active)) {
+                        superseded = activeId;
+                        break;
+                    }
+                }
+                // Watch for a terminal runtime failure so we fail fast (and red)
+                // instead of timing out green. The controller marks a crash-looping
+                // deployment ERROR — with a reason (e.g. a missing module) — within
+                // ~1min, long before this 5min promotion timeout.
+                const dep = await api.getDeployment(deployment.id);
+                const phase = dep.status?.phase;
+                if (phase === 'ERROR' || phase === 'BUILD_ERROR') {
+                    failure = { phase, reason: dep.status?.reason };
+                    break;
+                }
+                // CANCELED: the platform superseded this build before it produced a
+                // runnable (a sibling deployment of the app won the promotion).
+                if (phase === 'CANCELED') {
+                    superseded = dep.status?.reason ?? 'canceled';
+                    break;
+                }
+            }
+            catch (_error) {
+                // Ignore transient errors while polling and keep waiting
+                log.debug(`Polling app status failed, retrying...`);
+            }
+        }
+        if (promoted) {
+            log.info(`🌍 Deployment promoted and live, visit: https://${app.url}`);
+        }
+        else if (superseded) {
+            // Not a failure: the app IS live, just on a sibling deployment (e.g.
+            // duplicated workflows firing on the same push). Green exit — there is
+            // nothing for the user to fix in THIS run.
+            log.warn(`⚠️ Deployment superseded — a newer deployment of this app was promoted (${superseded}). The app is live: https://${app.url}`);
+        }
+        else if (failure) {
+            // Fail the command (non-zero exit → red GitHub Action) and surface the
+            // reason the controller captured so the user sees WHY without digging.
+            log.error(`❌ Deployment failed (${failure.phase}).`);
+            if (failure.reason)
+                log.error(failure.reason);
+            log.error(`Check the logs in the dashboard -> ${dashboard_url}`);
+            throw new Error(`Deployment ${deployment.id} failed with phase ${failure.phase}`);
+        }
+        else {
+            log.warn(`⌛ Timed out after 5min waiting for promotion. The deployment is still rolling out, check the dashboard -> ${dashboard_url}`);
+        }
+    }
+};
+
+export { launch };

package/dist/commands/deploy/resolve_app_id.js

@@ -3,14 +3,19 @@ import { getGitRemoteUrl } from '../../lib/git_remote.js';
 import { log } from '../../log.js';
 
 // app_id resolution (the user never has to look one up):
-//  1. explicit (positional on `deploy`, --app on subcommands)
+//  1. explicit (--app, on `deploy` and on every subcommand)
 //  2. OIDC in CI — the backend resolves the app from the linked repository
 //  3. locally — a legacy app_id in faable.json (older CLIs wrote it on
 //     `faable deploy link`; the current link only persists in the API)
 //  4. locally — the app whose linked repository matches the git origin remote
 //     of the working directory (repos are connected in the dashboard when the
 //     app is created, or via `faable deploy link`)
-const resolve_app_id = async (explicit, ctxAppId, api, workdir = process.cwd()) => {
+//
+// "No app here" is an answer, not an error — a bare `faable deploy` in an
+// unlinked directory lists the subcommands instead of failing, and only the
+// caller knows which of the two it wants. An AMBIGUOUS repository does throw:
+// several apps is a question only the user can answer.
+const find_app_id = async (explicit, ctxAppId, api, workdir = process.cwd()) => {
     const app_id = explicit || ctxAppId || Configuration.instance().app_id;
     if (app_id)
         return app_id;
@@ -25,10 +30,17 @@ const resolve_app_id = async (explicit, ctxAppId, api, workdir = process.cwd())
         }
         if (matches.length > 1) {
             const ids = matches.map(app => `${app.name} (${app.id})`).join(', ');
-            throw new Error(`Repository ${repository} is linked to several apps: ${ids}. Pass the app explicitly.`);
+            throw new Error(`Repository ${repository} is linked to several apps: ${ids}. Pass one with --app <app_id>.`);
         }
     }
-    throw new Error('No app linked to this repository. Link it from the dashboard (or run "faable deploy link"), or pass the app explicitly.');
+    return null;
+};
+// The same, for callers that have nothing to offer without an app.
+const resolve_app_id = async (explicit, ctxAppId, api, workdir = process.cwd()) => {
+    const app_id = await find_app_id(explicit, ctxAppId, api, workdir);
+    if (app_id)
+        return app_id;
+    throw new Error('No app linked to this repository. Link it from the dashboard (or run "faable deploy link"), or pass one with --app <app_id>.');
 };
 
-export { resolve_app_id };
+export { find_app_id, resolve_app_id };

package/dist/index.js

@@ -72,6 +72,14 @@ yg.scriptName('faable')
         // help, then fail red — a bad invocation must not exit 0.
         yg.showHelp();
         log.error(`❌ ${msg}`);
+        // The one unknown command worth naming: an app id passed positionally.
+        // `faable deploy <app_id> secrets list` used to deploy the working
+        // directory instead of listing secrets, so the id now lives in a flag —
+        // say so, or the migration reads as the CLI having lost a feature.
+        const stray = /Unknown commands?: (app_[A-Za-z0-9_-]+)/.exec(msg);
+        if (stray) {
+            log.error(`The app id goes in a flag, not as an argument: faable deploy --app ${stray[1]} [subcommand]`);
+        }
         process.exit(1);
     }
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faable/faable",
-  "version": "2.2.0",
+  "version": "3.1.0",
   "main": "dist/index.js",
   "license": "MIT",
   "author": "Marc Pomar <marc@faable.com>",