Faable — Deploy & Auth

Faable CLI

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

Full reference: faable.com/docs/cli.

To install the latest version:

npm i -g @faable/faable

Commands

Group	What it does	Docs
faable login / whoami / logout	Session management (device flow; CI uses OIDC, no login needed)	Authentication
faable project	The project commands act on: list, use, current, clear (or --project on any command)	Projects
faable deploy	launch (the default: a bare faable deploy deploys the current directory), then status, logs, deployments, inspect, trigger, redeploy, cancel, traffic, usage, quota, open	Deployment
faable deploy apps	list, get, create (from a GitHub repository, first deploy included), set (branch, root directory, deploy mode)	Apps
faable deploy secrets	Environment variables: list, set (KEY=VALUE, --env-file, or -f - from stdin), rm	Secrets
faable deploy domains	Custom domains: add (prints the CNAME), list, check, rm	Domains
faable deploy waf	Edge rules: block (403), sink (404 without waking the app), list, rm	Edge rules
faable auth users	list (FaableQL filters), get (federated identities included), suspend, reinstate	Users
faable auth actions	Login-flow hooks: list, get --code, create, update, rm	Actions
faable auth clients	OAuth clients: list, get --secret, create, rm	OAuth clients
faable auth logs	Audit log (read-only): list with filters, get	Audit logs

Every command has --help and --json. --app takes an app id, name or slug. The complete table is in the command reference.

MCP server

faable mcp runs the CLI as an MCP server over stdio, so Claude Code, Cursor or any MCP client can read your apps, deployments and logs — "why did my last deploy fail?" — and deploy, with your faable login session:

claude mcp add faable -- npx -y @faable/faable mcp

By default it exposes reads plus deploy_app (build the latest commit server-side). faable mcp --writes adds the reversible writes: create an app from a repository, set environment variables, add a domain, retry or cancel a build, change deploy settings. Nothing destructive is exposed. Secret values are never returned, and logs come back marked as data, not instructions.

Scripting and agents

Data goes to stdout, messages to stderr. With --json:

• every listing is {"object":"list","data":[…],"has_more","next_cursor"} (--limit, --starting-after, --all);
• every write returns what it changed, and a write with nothing to do returns {"result":"noop","reason"};
• a failure exits 1 with {"error":{"message","code","status","action"}} on stderr. Codes: not_logged_in, session_expired, account_suspended, apikey_session, forbidden, not_found, confirmation_required, app_required, usage, or the API's own code.

A program driving the CLI should set FAABLE_NONINTERACTIVE=1 (or pass --non-interactive): nothing prompts — a confirmation without --yes fails with confirmation_required —, the app is never inferred from the working directory, and faable deploy launch needs --app, --workdir and --yes. Pass secret values on stdin (faable deploy secrets set -f -), never as arguments.

Deploy

faable login
faable deploy                       # deploy the current directory (= deploy launch)
faable deploy launch --app app_x    # deploy another app, from anywhere
faable deploy apps create --repo acme/web   # create, link, first deploy
faable deploy --create site --workdir ./public --yes   # a new app from a folder (git or not)
faable deploy link --app web --repo acme/web      # link a repository to an existing app
faable deploy apps rm --app app_x   # delete an app (asks first; --yes to skip)
faable deploy status                # phase, URL and detected stack
faable deploy logs --build -n 100   # end of the build output (--follow to tail)
faable deploy traffic --since 7d    # status codes, top and failing paths
faable deploy secrets set KEY=value
faable deploy domains add app.example.com

Faable Auth

faable auth manages a Faable 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).

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"

# Bulk: pipe ids from a filtered listing
faable auth users list --suspended --json | jq -r '.data[].id' | faable auth users reinstate -y

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

See faable auth in the docs for every flag. The concepts behind each group are documented in Faable Auth: users & suspension, actions, login flows, OAuth clients and audit logs.

Documentation

The CLI is a thin client: what it deploys and what it manages is documented in the public docs, not here.

CLI

• Command reference — every command and flag
• Authentication — login, whoami, logout
• Deployment · Inspecting · Secrets · Domains · Edge rules · Faable Auth

Faable Deploy

• Get started — first deploy in minutes
• How deployment works — push-to-deploy, builds and releases
• Runtime — supported languages, framework detection, faable.json / Procfile overrides
• What the builder expects — build and start commands, $PORT, monorepos
• Environment & releases — secrets, env vars and release versions
• Custom domains and SSL certificates
• Web Application Firewall — the edge rules behind faable deploy waf
• Deploy from your own CI — OIDC, no login needed
• Framework guides: Next.js, Vite, Astro, Express, Django, FastAPI, Flask, PHP

Faable Auth

• Get started — create a tenant
• Clients · Connections · Social login · Passwordless
• Suspend users — what users suspend / reinstate do to sessions and tokens
• Login flows and actions — the hooks managed by auth actions
• Logs — the audit trail read by auth logs
• OAuth 2.0 flows · OpenID Connect · Validate access tokens