Skip to content

Latest commit

Β 

History

History
186 lines (146 loc) Β· 11.3 KB

README.md

File metadata and controls

186 lines (146 loc) Β· 11.3 KB

Faable CLI: deploy and run your apps from the terminal

npm version MIT license Documentation

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 challenge Faable Challenge bot protection: sites list, sites create (prints the site key and, once, the secret), sites update, sites delete, sites rotate-secret, usage (verifications vs the plan's quota) Faable Challenge
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, update (URLs, profile fields, login methods, --signup-protection off|on_risk|always), 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, rotate a Challenge secret. delete_app and delete_challenge_site are the local server's only deletions. 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 clients update my-app --signup-protection always   # bot check on every signup
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

Faable Deploy

Faable Auth

Support

License

MIT Β© Faable Cloud SLU