CLI

The FaceGate CLI sets up face auth in your project, enrolls faces from image files, and checks server health — all from the terminal. It ships as the facegate package and runs with npx, so there's nothing to install globally.

Usage

npx facegate <command> [options]

Every command runs against your FaceGate server. After init, the CLI reads your API key and server URL from .facegate.config.json in the current directory, so you rarely pass them by hand.

Command	What it does
`init`	Detect your framework and write `.facegate.config.json`
`enroll`	Enroll a face from an image file
`status`	Check server health, version, and uptime

facegate test exists but is not yet shipped — see Not yet available below.

init

Initializes FaceGate in your project. Run it from your project root, where your package.json lives.

npx facegate init

init reads package.json, detects your framework, and writes a .facegate.config.json file. It then prints a copy-paste integration snippet for the framework it found (and a Supabase variant if @supabase/supabase-js is a dependency).

Options

Flag	Default	Description
`--api-key <key>`	`fg_test_REPLACE_ME`	Your FaceGate API key. If omitted, a placeholder is written and you replace it later.
`--base-url <url>`	`https://api.facegate.ai`	FaceGate server URL. Override for self-hosted deployments.

Framework detection

Detection runs off your dependencies and devDependencies, picking the most specific match:

Detected	Trigger dependency
Next.js	`next`
Create React App	`react-scripts`
Remix	`@remix-run/react`
SvelteKit	`@sveltejs/kit`
Nuxt	`nuxt`
Vite	`vite`
Node.js	none of the above

If @supabase/supabase-js is present, the snippet uses the Supabase adapter so a successful scan mints a real Supabase session.

Config shape

init writes .facegate.config.json to the current directory:

{
  "apiKey": "fg_test_REPLACE_ME",
  "baseUrl": "https://api.facegate.ai",
  "framework": "nextjs"
}

If you didn't pass --api-key, replace the placeholder before running enroll or status. Grab a key from the dashboard.

enroll

Enrolls a face from an image file. The CLI reads the photo, base64-encodes it, and sends it to the server, which extracts and indexes the face vectors. The photo itself is discarded after processing.

npx facegate enroll --name "Ada Lovelace" --photo ./ada.jpg

Options

Flag	Required	Description
`--name <name>`	Yes	The person's name.
`--photo <path>`	Yes	Path to a JPEG or PNG file. Resolved relative to the current directory.
`--role <role>`	No	Optional role to assign to the enrolled user.
`--api-key <key>`	No	Override the API key from config.
`--base-url <url>`	No	Override the server URL from config.

On success, the CLI prints the new user ID, face ID, and the number of vectors indexed:

  Enrolling "Ada Lovelace"...
 
  Enrolled successfully.
  User ID:   usr_9f3c2a
  Face ID:   fac_71b0e4
  Vectors:   1

Assign a role inline:

npx facegate enroll --name "Ada Lovelace" --photo ./ada.jpg --role guard

API key resolution is explicit flag, then .facegate.config.json, then error. If neither is set, the CLI exits with a message telling you to pass --api-key or run facegate init first.

status

Checks your FaceGate server's health and reports its status, version, provider, and uptime.

npx facegate status

  Checking https://api.facegate.ai...
 
  Status:    OK (healthy)
  Version:   0.1.0
  Provider:  rekognition
  Uptime:    3h 12m

Status maps to one of three states: OK (healthy), DEGRADED (degraded), or DOWN. If the health check fails outright, the command exits non-zero with the error.

Options

Flag	Description
`--api-key <key>`	Override the API key from config.
`--base-url <url>`	Override the server URL from config. Point it at a self-hosted server to check that instance.

Configuration resolution

enroll and status resolve their API key and server URL in the same order:

The explicit --api-key / --base-url flag, if passed.
The matching value in .facegate.config.json.
For --base-url only, the default https://api.facegate.ai. For the API key, an error if neither flag nor config supplies one.

This means once you've run init, plain npx facegate status and npx facegate enroll … work with no extra flags.

Not yet available

facegate test is registered but not implemented yet. Today it only prints a playground URL and a note that the playground is coming in Phase 3 — it does not open a browser or run any face auth test:

  Open this URL to test face auth:
 
  https://facegate.ai/playground#key=fg_test_demo
 
  (Playground coming in Phase 3)

Until the playground ships, verify your integration with status (server reachable and healthy) and enroll (a face indexes successfully), or test the live flow with the React SDK.

Next steps

React SDK — the <FaceGate /> drop-in component, props, and theming.
REST API — call the enrollment and verification endpoints directly.