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.
Install
Requires Node.js 22.8 or later.
npm i -g @faable/faable
Quick start
faable login # sign in from your browser
faable deploy # deploy the current directory
faable deploy status
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 organization | Group projects under a company: list, get, create, projects add/rm, admins add/rm (org for short) | Organizations |
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/Procfileoverrides - 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/reinstatedo 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
Support
- Documentation: faable.com/docs
- Community help, on every plan: GitHub Discussions
- Help from the Faable team, on the Hobby and Pro plans: [email protected]. See the support page
- Bugs and feature requests: open an issue
- Security issues: report them privately to [email protected], not in a public issue
License
MIT © Faable Cloud SLU