@facilio/cli

The unified Facilio CLI — one login for every Facilio product.

npm install -g @facilio/cli
facilio login
facilio vibe deploy
facilio connections search create xero invoice

Migrating from @facilio/vibe-cli? The vibe binary is gone; every command now lives under facilio vibe … (e.g. vibe deploy → facilio vibe deploy). Your existing login session is migrated automatically on first run.

Universal commands

| Command | What it does | |---|---| | facilio login | Sign in via the OAuth2 device-authorization flow (RFC 8628). Works on laptops, over SSH, and inside containers — no local callback port needed. One session covers every product namespace. Saves under the default profile unless --profile <name> is given (see Multiple accounts). | | facilio login --api-key <key> | Non-interactive sign-in for CI. Pass - to read the key from stdin (keeps it out of shell history). Use --region <key> (US, UK, AE, AU, …; default US) so vibe + MCP URLs resolve correctly. API-key sessions cover vibe commands only. | | facilio logout | Revoke the active profile server-side (best-effort) and clear it locally. --profile <name> targets a specific profile; --all logs out of every profile. | | facilio whoami | Show the active session: user, active profile, auth source, resolved endpoints. | | facilio accounts (ls) | List all saved account profiles, marking the active one. | | facilio switch [profile] | Change the active account profile. With no argument, shows an interactive picker. | | facilio help [command] | Help for any command or namespace. |

facilio vibe — build and deploy Vibe apps

| Command | What it does | |---|---| | facilio vibe deploy | Zip build.publish, upload, wait for deployment to finish. --prod marks production. Build your app yourself first (e.g. npm run build). | | facilio vibe app create / app list | Create a new app (prompts for name/description/logo) / list apps in your org. | | facilio vibe db create\|import\|tables\|describe | Provision the app database, import CSVs as tables, inspect schema. | | facilio vibe function create\|update\|list\|get\|delete\|build\|run | Manage an app's ai-studio functions (compiled to WASM). |

Project config stays in vibe.json at your project root — unchanged from the old CLI (build.publish points at your build output folder).

facilio connections — 1000+ integrated apps

Backed by the Facilio Connections MCP server; the CLI sends your login token directly, so there is no separate sign-in.

| Command | What it does | |---|---| | facilio connections search <query…> | Find actions by use case, e.g. search create xero invoice. | | facilio connections schemas <slug…> | Show an action's input JSON Schema (--with-output adds the output schema). | | facilio connections list <connection…> | Show your connected accounts for connections (e.g. list xero). | | facilio connections link <connection> | Authorize a connection — opens the target app's OAuth page. --wait blocks until ACTIVE. | | facilio connections unlink <connection> | Remove your authorization (prompts to confirm; --yes to skip). | | facilio connections wait <connection…> | Poll until connection(s) become ACTIVE (--mode all, --timeout <s>). | | facilio connections execute <action_slug…> --params '<json>' | Run one or more actions. --get-schema prints the input schema instead of running; --dry-run validates args against the schema and previews the request without executing; repeat --params once per slug to run several in parallel; --params - reads stdin; --account <slug> targets a connected account; --file batch.json runs a batch. |

Every connections command accepts --json (raw payloads for scripts/agents), --mcp-url <url> (non-production servers), and --app <slug> (scope all calls to one connection).

A typical first run:

facilio connections search create xero invoice   # discover action slugs
facilio connections link xero --wait             # authorize Xero, wait for ACTIVE
facilio connections schemas xero.create_invoice  # see required arguments
facilio connections execute xero.create_invoice --params '{"contact_id":"…","amount":100}'

How login works

facilio login uses the OAuth2 device-authorization grant (RFC 8628) — the same model GitHub CLI, gcloud, and AWS SSO use. Credentials land in the OS secret store (macOS Keychain / Linux secret-service / Windows DPAPI), with a 0600 file fallback at ~/.facilio/credentials.json. Access tokens refresh automatically; concurrent invocations coordinate through a lock file so the rotated refresh token is never burned twice.

Multiple accounts (profiles)

Keep several accounts side by side — e.g. a work org and a personal org, or US and UK data centers — and switch between them, GitHub-CLI style. Each account is a named profile (AWS-CLI style); the active profile is used by default.

facilio login --profile work         # sign in, saved as "work" (now active)
facilio login --profile personal     # add a second account (now active)
facilio accounts                      # list profiles; "*" marks the active one
facilio switch work                   # make "work" active
facilio logout --profile personal     # drop just that account
facilio logout --all                  # drop every account

Run a single command as a specific profile without changing the active one — handy in scripts — with the global --profile flag (before or after the subcommand) or FACILIO_PROFILE:

facilio --profile work vibe deploy
facilio vibe deploy --profile work
FACILIO_PROFILE=work facilio connections search create xero invoice

Profile resolution order for any command: an explicitly requested profile (--profile / FACILIO_PROFILE) → FACILIO_API_KEY (CI) → the active profile. Plain facilio login (no --profile) targets the default profile, so single-account users and existing sessions are unaffected — an existing session is migrated into default automatically on first run.

Regions

The token response carries your home region key (US, AE, AU, …). Product endpoints resolve per-region from the table in src/core/regions.ts at call time — no service key is sent at login and no product URL is baked into the session. Precedence: env override (FACILIO_VIBE_SERVER_URL / FACILIO_CONNECTIONS_SERVER_URL) → pinned --server (vibe only) → region table → default. facilio whoami shows the resolved endpoints.

Environment variables

FACILIO_* is canonical; the legacy VIBE_* names still work as fallbacks.

| Variable | Purpose | |---|---| | FACILIO_API_KEY | Zero-config CI auth (used when no profile is explicitly requested). | | FACILIO_REGION | Region for FACILIO_API_KEY sessions (US, UK, AE, AU, …; default US). | | FACILIO_PROFILE | Run commands as a specific saved profile (same as the global --profile flag). | | FACILIO_IDENTITY_SERVER_URL | Identity-service base URL override (was FACILIO_IDENTITY_URL, still honoured). | | FACILIO_VIBE_SERVER_URL | Vibe product-server URL override, beats the region table (was FACILIO_SERVER_URL, still honoured). | | FACILIO_CONNECTIONS_SERVER_URL | Connections MCP endpoint override, beats the region table (was FACILIO_MCP_URL, still honoured). | | FACILIO_CLIENT_ID | OAuth client id override. | | FACILIO_NO_KEYCHAIN=1 | Force file-based credential storage (CI). |

Local development

Point each backend at your local stack independently — set any subset:

export FACILIO_IDENTITY_SERVER_URL=http://localhost:8090/identity
export FACILIO_VIBE_SERVER_URL=http://localhost:8080
export FACILIO_CONNECTIONS_SERVER_URL=http://localhost:9000/mcp

Development

npm install
npm run dev -- --help    # run from source (tsx)
npm test                 # vitest
npm run build            # tsc → dist/

Product namespaces live under src/products/<name>/ and register their command tree through the ProductModule contract in src/products/types.ts — adding a new Facilio product CLI is one folder plus one line in the registry in src/index.ts.