@faable/faable 2.1.0 → 3.0.0

package/README.md

@@ -9,67 +9,104 @@
   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` | Deploy 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
+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/FaableApi.js

@@ -252,9 +252,9 @@ class FaableApi {
     async addAppWafRule(app_id, params) {
         return data(this.client.post(`/app/${app_id}/waf/rules`, params));
     }
-    async removeAppWafRule(app_id, pattern) {
+    async removeAppWafRule(app_id, params) {
         return data(this.client.delete(`/app/${app_id}/waf/rules`, {
-            data: { pattern }
+            data: params
         }));
     }
 }

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/index.js

@@ -22,13 +22,18 @@ import { is_superseded } from './superseded.js';
 import { waf } from './waf/index.js';
 
 const deploy = {
-    command: 'deploy [app_id]',
+    // No positional: `deploy` takes ONLY subcommands. 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; with no positional, .strictCommands() in
+    // src/index.ts rejects it as an unknown command. Target another app with
+    // --app, exactly like every subcommand does.
+    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).
+        // Product subcommands live under `deploy`.
         return yargs
             .command(secrets)
             .command(domains)
@@ -43,9 +48,10 @@ const deploy = {
             .command(redeploy)
             .command(cancel)
             .command(link)
-            .positional('app_id', {
+            .option('app', {
+            alias: 'a',
             type: 'string',
-            description: 'App Identifier'
+            description: 'App Identifier (defaults to the app linked to this repository)'
         })
             .option('workdir', {
             alias: 'w',
@@ -62,22 +68,21 @@ const deploy = {
             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_id);
+        const ctx = await requireApi(args.app);
         const { api } = ctx;
         const config = Configuration.instance().deployConfig();
-        const app_id = await resolve_app_id(args.app_id, ctx.appId, api, workdir);
+        const app_id = await resolve_app_id(args.app, 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.
+        // 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',

package/dist/commands/deploy/resolve_app_id.js

@@ -3,7 +3,7 @@ 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)
@@ -25,10 +25,10 @@ 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.');
+    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 };

package/dist/commands/deploy/waf/add_rule.js

@@ -1,24 +1,83 @@
 import { log } from '../../../log.js';
 
+/** How a rule reads in a sentence, for the confirmation the user gets back. */
+const describe_selector = (s) => {
+    if (s.pattern && s.user_agent) {
+        return `requests for ${s.pattern} from user-agents matching ${s.user_agent}`;
+    }
+    if (s.user_agent)
+        return `requests from user-agents matching ${s.user_agent}`;
+    return `requests for ${s.pattern}`;
+};
+/** Does this returned rule carry everything we asked for? */
+const rule_matches_request = (rule, want, action) => rule.action === action &&
+    (rule.pattern ?? '') === (want.pattern ?? '') &&
+    (rule.user_agent ?? '') === (want.user_agent ?? '');
 /**
  * Shared handler for `block` and `sink` — the two differ only in the action
  * they store and in what the edge answers, so the flow (resolve app, write,
- * explain, tell the user how to check) lives here once.
+ * verify, explain, tell the user how to check) lives here once.
  */
 const add_rule = async (opts) => {
-    const { api, app_id, app_name, app_url, pattern, action, description } = opts;
-    await api.addAppWafRule(app_id, { pattern, action, description });
+    const { api, app_id, app_name, app_url, pattern, user_agent, action, description, force } = opts;
+    const want = { pattern, user_agent };
+    const waf = await api.addAppWafRule(app_id, {
+        pattern,
+        user_agent,
+        action,
+        description,
+        force
+    });
+    // Read the rule back before telling the user it worked.
+    //
+    // An older Faable server has no `user_agent` on this endpoint and drops it
+    // silently, storing the path half on its own — which turns "block /login for
+    // this bot" into "block /login for everyone". No server-side schema can
+    // prevent that (the old server is the old code), so the client checks that
+    // what came back is what it asked for, and undoes the write if it is not.
+    if (user_agent &&
+        !waf.rules.some(r => rule_matches_request(r, want, action))) {
+        await api
+            .removeAppWafRule(app_id, { pattern, user_agent, action })
+            // If the rollback itself is unsupported, fall back to the path-only
+            // shape the old server actually stored.
+            .catch(() => api.removeAppWafRule(app_id, { pattern, action }))
+            .catch(() => undefined);
+        throw new Error(`This Faable server does not support user-agent rules yet, so the rule was not created.\n` +
+            `  Update the CLI and try again, or ask support to upgrade the platform.`);
+    }
     const answer = action === 'deny' ? '403' : '404';
-    log.info(`🛡️  ${pattern} → ${answer} at the edge for ${app_name} (${app_id}).`);
+    log.info(`🛡️  ${describe_selector(want)} → ${answer} at the edge`);
+    log.info(`   for ${app_name} (${app_id}).`);
     log.info(``);
     log.info(action === 'deny'
         ? `Matching requests are blocked before they reach your app, so they no longer wake it.`
         : `Faable answers matching requests with a ${answer} itself, so they no longer wake your app.`);
+    if (user_agent) {
+        log.info(``);
+        log.info(`⚠️  A user-agent rule has no path restriction: it applies to EVERY path` +
+            (pattern ? ` that also matches ${pattern}.` : ` on this app.`));
+        if (action === 'sink' && !pattern) {
+            // Worth saying out loud: the sink router sits above the sleep-through
+            // probe, so a monitor caught by this rule gets the 404 instead of the
+            // health answer it expects.
+            log.info(`   If that user-agent is an uptime monitor, it will now see a 404 instead of a health check.`);
+        }
+    }
     log.info(``);
     log.info(`It takes about 20s to reach the edge. Then check it with:`);
-    log.info(`  curl -s -o /dev/null -w '%{http_code}\\n' https://${app_url}<path>`);
+    log.info(user_agent
+        ? `  curl -s -o /dev/null -w '%{http_code}\\n' -A '${user_agent}' https://${app_url}/`
+        : `  curl -s -o /dev/null -w '%{http_code}\\n' https://${app_url}<path>`);
     log.info(``);
-    log.info(`Undo: faable deploy waf rm '${pattern}' -a ${app_id}`);
+    log.info(`Undo: faable deploy waf rm ${undo_args(want)} -a ${app_id}`);
 };
+/** The exact arguments that reverse this rule. */
+const undo_args = (s) => [
+    s.pattern ? `'${s.pattern}'` : '',
+    s.user_agent ? `--user-agent '${s.user_agent}'` : ''
+]
+    .filter(Boolean)
+    .join(' ');
 
-export { add_rule };
+export { add_rule, describe_selector, rule_matches_request, undo_args };

package/dist/commands/deploy/waf/block.js

@@ -3,13 +3,17 @@ import { resolve_app_id } from '../resolve_app_id.js';
 import { add_rule } from './add_rule.js';
 
 const waf_block = {
-    command: 'block <pattern>',
-    describe: 'Block a path at the edge with a 403 (never reaches your app)',
+    command: 'block [pattern]',
+    describe: 'Block requests at the edge with a 403 (they never reach your app)',
     builder: yargs => yargs
         .positional('pattern', {
         type: 'string',
-        demandOption: true,
         description: 'Anchored path regex, e.g. ^/\\.well-known/ (quote it in your shell)'
+    })
+        .option('user-agent', {
+        alias: 'u',
+        type: 'string',
+        description: 'RE2 fragment matched against User-Agent, e.g. YisouSpider. With a path, BOTH must match.'
     })
         .option('app', {
         alias: 'a',
@@ -20,8 +24,23 @@ const waf_block = {
         alias: 'd',
         type: 'string',
         description: 'Why this rule exists (shown in `waf list`)'
+    })
+        .option('force', {
+        type: 'boolean',
+        default: false,
+        description: 'Accept a user-agent that also matches a known search/AI crawler or uptime monitor'
+    })
+        .check(({ pattern, userAgent }) => {
+        if (!pattern && !userAgent) {
+            throw new Error('Give a path pattern, --user-agent, or both.\n' +
+                "  e.g. faable deploy waf block '^/wp-admin'\n" +
+                '       faable deploy waf block --user-agent YisouSpider');
+        }
+        return true;
     })
         .example("$0 deploy waf block '^/\\.well-known/'", 'Stop scanner probes under /.well-known from waking the app')
+        .example('$0 deploy waf block --user-agent YisouSpider', 'Refuse one crawler outright, on every path')
+        .example("$0 deploy waf block '^/api/' --user-agent curl", 'Refuse /api/ to that user-agent only, leaving browsers untouched')
         .showHelpOnFail(false),
     handler: async (args) => {
         const ctx = await requireApi();
@@ -33,8 +52,10 @@ const waf_block = {
             app_name: app.name,
             app_url: app.url,
             pattern: args.pattern,
+            user_agent: args.userAgent,
             action: 'deny',
-            description: args.description
+            description: args.description,
+            force: args.force
         });
     }
 };

package/dist/commands/deploy/waf/format.js

@@ -3,7 +3,9 @@ const action_label = (action) => action === 'sink'
     ? '404 (answered by Faable, app not woken)'
     : action === 'deny'
         ? '403 (blocked at the edge)'
-        : action;
+        : action === 'probe'
+            ? 'answered by Faable, app not woken (uptime monitors)'
+            : action;
 /**
  * Render the effective WAF of an app.
  *
@@ -22,9 +24,13 @@ const format_waf = (waf) => {
         out.push('  (none)');
     }
     for (const p of waf.platform_profiles) {
-        out.push(`  • ${p.name} — ${p.rule_count} rule(s), ${action_label(p.action)}`);
+        // Say what the ruleset matches ON, not just what it answers: without it a
+        // `probe` profile of user-agents reads as if it blocked paths.
+        const on = p.match === 'user_agent' ? ' by user-agent' : '';
+        out.push(`  • ${p.name} — ${p.rule_count} rule(s)${on}, ${action_label(p.action)}`);
         for (const r of p.rules ?? []) {
-            out.push(`      ${r.pattern}${r.description ? `  # ${r.description}` : ''}`);
+            const what = p.match === 'user_agent' ? `UA ~ ${r.pattern}` : r.pattern;
+            out.push(`      ${what}${r.description ? `  # ${r.description}` : ''}`);
         }
     }
     out.push('');
@@ -33,11 +39,26 @@ const format_waf = (waf) => {
         out.push('  (none)');
     }
     for (const r of waf.rules) {
-        out.push(`  • ${r.pattern} → ${action_label(r.action)}`);
+        out.push(`  • ${rule_subject(r)} → ${action_label(r.action)}`);
         if (r.description)
             out.push(`      ${r.description}`);
     }
     return out;
 };
+/**
+ * What a rule selects, in one line.
+ *
+ * The three shapes have to be visibly different here: a user-agent rule has no
+ * path restriction (it applies to the whole app) and a combined one is an AND,
+ * so printing either as a bare pattern would misrepresent its reach.
+ */
+const rule_subject = (r) => {
+    if (r.pattern && r.user_agent) {
+        return `${r.pattern} + UA ~ ${r.user_agent}`;
+    }
+    if (r.user_agent)
+        return `UA ~ ${r.user_agent} (any path)`;
+    return r.pattern ?? '(unknown)';
+};
 
-export { action_label, format_waf };
+export { action_label, format_waf, rule_subject };

package/dist/commands/deploy/waf/rm.js

@@ -1,30 +1,57 @@
 import { requireApi } from '../../../api/context.js';
 import { log } from '../../../log.js';
 import { resolve_app_id } from '../resolve_app_id.js';
+import { describe_selector } from './add_rule.js';
 
 const waf_rm = {
-    command: 'rm <pattern>',
+    command: 'rm [pattern]',
     describe: 'Remove one of your WAF rules',
     builder: yargs => yargs
         .positional('pattern', {
         type: 'string',
-        demandOption: true,
         description: 'The exact pattern to remove (see `faable deploy waf list`)'
+    })
+        // A rule is addressed by everything that defines it, not by its path
+        // alone: "/login" and "/login for YisouSpider" are two different rules
+        // that share a pattern, and removing one must not take out the other.
+        .option('user-agent', {
+        alias: 'u',
+        type: 'string',
+        description: 'The user-agent of the rule to remove'
+    })
+        .option('action', {
+        type: 'string',
+        choices: ['deny', 'sink'],
+        description: 'Only needed when the same rule exists as both'
     })
         .option('app', {
         alias: 'a',
         type: 'string',
         description: 'App Identifier (defaults to the linked app)'
+    })
+        .check(({ pattern, userAgent }) => {
+        if (!pattern && !userAgent) {
+            throw new Error('Give the path pattern, --user-agent, or both.');
+        }
+        return true;
     })
         .example("$0 deploy waf rm '^/robots\\.txt$'", 'Stop handling /robots.txt at the edge')
+        .example('$0 deploy waf rm --user-agent YisouSpider', 'Stop blocking that crawler')
         .showHelpOnFail(false),
     handler: async (args) => {
         const ctx = await requireApi();
         const app_id = await resolve_app_id(args.app, ctx.appId, ctx.api);
         const app = await ctx.api.getApp(app_id);
-        await ctx.api.removeAppWafRule(app_id, args.pattern);
-        log.info(`🗑️  Removed ${args.pattern} from ${app.name} (${app_id}).`);
-        log.info(`Requests for it reach your app again within ~20s, once the edge picks up the change.`);
+        await ctx.api.removeAppWafRule(app_id, {
+            pattern: args.pattern,
+            user_agent: args.userAgent,
+            action: args.action
+        });
+        log.info(`🗑️  Removed ${describe_selector({
+            pattern: args.pattern,
+            user_agent: args.userAgent
+        })} from ${app.name} (${app_id}).`);
+        log.info(`They reach your app again within ~20s, once the edge picks up the change.`);
     }
 };
 

package/dist/commands/deploy/waf/sink.js

@@ -3,13 +3,17 @@ import { resolve_app_id } from '../resolve_app_id.js';
 import { add_rule } from './add_rule.js';
 
 const waf_sink = {
-    command: 'sink <pattern>',
-    describe: 'Answer a path with a 404 from Faable, without waking your app',
+    command: 'sink [pattern]',
+    describe: 'Answer requests with a 404 from Faable, without waking your app',
     builder: yargs => yargs
         .positional('pattern', {
         type: 'string',
-        demandOption: true,
         description: 'Anchored path regex, e.g. ^/robots\\.txt$ (quote it in your shell)'
+    })
+        .option('user-agent', {
+        alias: 'u',
+        type: 'string',
+        description: 'RE2 fragment matched against User-Agent, e.g. YisouSpider. With a path, BOTH must match.'
     })
         .option('app', {
         alias: 'a',
@@ -20,11 +24,25 @@ const waf_sink = {
         alias: 'd',
         type: 'string',
         description: 'Why this rule exists (shown in `waf list`)'
+    })
+        .option('force', {
+        type: 'boolean',
+        default: false,
+        description: 'Accept a user-agent that also matches a known search/AI crawler or uptime monitor'
+    })
+        .check(({ pattern, userAgent }) => {
+        if (!pattern && !userAgent) {
+            throw new Error('Give a path pattern, --user-agent, or both.\n' +
+                "  e.g. faable deploy waf sink '^/wp-admin'\n" +
+                '       faable deploy waf sink --user-agent YisouSpider');
+        }
+        return true;
     })
         .example("$0 deploy waf sink '^/robots\\.txt$'", 'Let Faable answer /robots.txt with a 404 instead of starting your app')
-        .epilogue('Use `sink` for paths your app does not serve anyway: Faable replies ' +
-        'with the same 404 your app would have, without the cold start. ' +
-        'Use `block` instead when you want the request refused outright.')
+        .example('$0 deploy waf sink --user-agent SemrushBot', 'Answer one crawler with a 404 instead of waking the app for it')
+        .epilogue('Use `sink` for requests your app would 404 anyway: Faable replies ' +
+        'with the same 404, without the cold start. Use `block` instead ' +
+        'when you want the request refused outright.')
         .showHelpOnFail(false),
     handler: async (args) => {
         const ctx = await requireApi();
@@ -36,8 +54,10 @@ const waf_sink = {
             app_name: app.name,
             app_url: app.url,
             pattern: args.pattern,
+            user_agent: args.userAgent,
             action: 'sink',
-            description: args.description
+            description: args.description,
+            force: args.force
         });
     }
 };

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.1.0",
+  "version": "3.0.0",
   "main": "dist/index.js",
   "license": "MIT",
   "author": "Marc Pomar <marc@faable.com>",