CLI

The Enlitt CLI is the terminal client for your business account. A coding agent can drive it without ever seeing a credential. You approve the sign-in in your browser, and the CLI writes secret keys straight to a file you name.

This page is the complete reference. It covers every command, flag, default, output shape, finding, and error code, plus recipes for the common tasks.

Install

npm i -D @enlitt/cli
npx enlitt --help
npx enlitt key rotate --help   # one command's flags, with descriptions and defaults

The CLI needs Node.js 22 or later and has no runtime dependencies.

Choose the deployment: --env

Every command talks to one Enlitt deployment, chosen by --env:

Each deployment has its own accounts, applications, keys, and CLI sign-in, kept in a separate credential file. When you work against staging, pass --env staging on every command, including login, reauth, doctor, and the commands the CLI prints for you. A command without it acts on production. The commands the CLI prints already carry the right --env.

Sign in and approve

npx enlitt login

The CLI prints a URL and a short code (XXXX-XXXX) and opens your browser. Check that the code matches, then approve while signed in to your business account. If you have no business yet, the approval page lets you create one. The CLI never asks for a password, sign-in code, Google credential, or cookie.

A coding agent's shell call times out long before a person finishes approving, so split the step in two:

npx enlitt login --no-wait    # prints the URL and code once, then exits 0
# ... the developer opens the URL and approves ...
npx enlitt login --wait       # resumes and finishes sign-in

--no-wait saves the pending approval locally. --wait resumes it and polls until you approve or deny. --timeout <seconds> bounds one --wait. A timeout fails with authorization_pending but keeps the pending approval, so run --wait again. An approval left unanswered expires after about 10 minutes; then start again with --no-wait.

A sign-in is valid for 90 days or until revoked. It is bound to one business: the one you chose when approving. To work in another business, see Several businesses.

Fresh approval for key commands

Creating, rotating, and revoking a key, and listing Read-only keys, also need an approval from the last 15 minutes. When the last one is older, the command fails with reauthentication_required and changes nothing. Then:

npx enlitt reauth --no-wait   # prints a URL; the developer approves
npx enlitt reauth --wait
# rerun the key command

In an interactive terminal, the key command runs this flow itself and retries once. One approval covers every key command for the next 15 minutes.

Roles: what your sign-in can do

The CLI acts with your role in the business, and the role decides which commands run. npx enlitt whoami prints your role and, in business.allowed_commands, the commands you can run.

¹ A viewer can rerun setup on an application that already exists, which links the project and writes ENLITT_CLIENT_ID, but cannot create one. ² Without the owner role, setup does everything except create the key. See below.

A command your role cannot run fails with insufficient_permissions before it changes anything. The message names your role and the business, and action says who can do it:

• Key commands: only the owner can create, rotate, or revoke keys. Ask the owner to run the command, or to create the key on the dashboard's Keys page.
• App commands: ask the owner or an admin to make you a developer or admin, or to run the command for you.

The server checks your role on every request, so a role change applies to your next command, and removing you from the business stops your sign-in at once. Members, payouts, and ownership stay in the dashboard for every role (see What the CLI cannot do).

setup as a developer or admin

setup registers and links the application and writes ENLITT_CLIENT_ID, then skips the key and exits 0. Its output lists the key under missing, with the action to take:

{
  "wrote": ["ENLITT_CLIENT_ID"],
  "missing": [
    {
      "variable": "ENLITT_SECRET_KEY",
      "action": "Only the business owner can create keys. Ask the owner to create an app key for My App (app_…) and put it in ENLITT_SECRET_KEY in .env.local."
    }
  ]
}

Ask the owner for the key, and let them put it in the env file themselves; never send it through a chat. Until then, doctor reports secret_key_missing.

Several businesses

One login can own a business and be a member of others. A CLI sign-in acts for exactly one of them: the one you choose on the approval page. When you belong to more than one, that page shows a Business picker with your role in each. Choosing a business there also switches the business your dashboard shows.

To work in another business, sign in again and pick it when approving:

npx enlitt login --no-wait
npx enlitt login --wait
npx enlitt whoami

The new sign-in replaces the old one for that --env. In the dashboard, switch businesses from the business menu at the top of the sidebar; All businesses and invitations lists every business you can reach and the invitations waiting for you.

Output, exit codes, and global flags

• Streams. Results go to stdout. Progress text, such as a URL to open or "waiting for approval…", always goes to stderr, so it never corrupts a JSON document. Without --json, an error goes to stderr as error: <message> and next: <action>.
• Exit codes. 0 success. 1 any refusal or failure, including confirmation_required and a doctor run with an error finding. 2 a usage error: an unknown command or flag, a missing flag, or a malformed value.
• Stable JSON. A result may gain fields but never loses or renames one. IDs are Enlitt's wire IDs. Money is a NANOUSD integer string in JSON (1 USD = 1,000,000,000 NANOUSD) and USD in human output.
• Dates in flags are YYYY-MM-DD, UTC, inclusive. Timestamps in output are RFC 3339.

Common tasks

Wire a new project

From the project root (the folder with package.json):

npx enlitt login --no-wait && npx enlitt login --wait
npx enlitt setup --name "My App" \
  --redirect-uri http://localhost:3000/auth/enlitt/callback \
  --origin http://localhost:3000
npx enlitt doctor

setup registers a test application, writes enlitt.json, and writes ENLITT_CLIENT_ID and a new App key (ENLITT_SECRET_KEY) to .env.local. Only the owner can create the key; for other roles see setup as a developer or admin. It prints variable names only. Then mount the login routes from Login and sessions. Against staging, add --env staging to each command; setup then also writes ENLITT_BASE_URL.

Add a callback URL or a port

Register both the callback URL and its origin. Leave enlitt.json linked so the CLI knows the application:

npx enlitt app update --add-redirect-uri http://localhost:3001/auth/enlitt/callback \
  --add-origin http://localhost:3001

http://localhost:3000 and http://localhost:3001 are different callbacks; see the redirect rules.

Diagnose a login that fails

npx enlitt doctor --callback-url http://localhost:3001/auth/enlitt/callback

doctor checks the sign-in, the project link, the env file, the client ID, the secret key, and whether the callback and origin are registered exactly. Each finding carries the exact command that fixes it. See doctor findings.

Answer a question about the account

Replace a lost or leaked secret

npx enlitt key list                                   # find the key id
npx enlitt key rotate <key_id> --write-env .env.local

Rotation keeps the key's identity and writes the new secret over the old value in the env file. The output says when the old secret stops working (previous_key.expires_at), so you know how long a deployed server can keep the old value. Update every deployment's secret store before then. A live key needs --confirm.

Move to live

A live application is a separate registration with its own client ID and key. Keep the test one for development:

npx enlitt app create --name "My App" --environment live \
  --redirect-uri https://my-app.example/auth/enlitt/callback \
  --origin https://my-app.example --confirm
npx enlitt key create --app <live_app_id> --name production \
  --write-env .env.production.local

Then copy that secret into the production server's secret manager. A coding agent must ask you before passing --confirm.

Command reference

login

npx enlitt login [--label <text>] [--no-browser] [--no-wait | --wait] [--timeout <seconds>]

Without --no-wait or --wait, it starts and waits in one run. Output: { login: { email }, business: { id, name }, credential_id, expires_at }. With --no-wait: { status: "pending", verification_uri_complete, user_code, expires_at }. A new sign-in replaces and revokes the previous one for the same --env.

reauth

npx enlitt reauth [--no-browser] [--no-wait | --wait] [--timeout <seconds>]

Same flags as login. Needs a sign-in. Must be approved by the same login, for the same business. Output: { reauthenticated_at }.

logout

npx enlitt logout revokes this CLI sign-in on the server and deletes the local credential, even if the server call failed. Output: { logged_out, revoked }. Without a sign-in it prints { logged_out: false, revoked: false } and exits 0.

whoami

npx enlitt whoami prints { login: { email }, business: { id, name, role, permissions, allowed_commands }, environment, api_origin, credential_expires_at }. allowed_commands lists the commands your role can run, such as "app create". The human form prints them as "You can run: …" and "Not with your role: …".

status

npx enlitt status is whoami plus the project link, and works when signed out. Output: { logged_in, login?, business?, project: { linked, application_id?, env_file?, env_file_has: { ENLITT_SECRET_KEY, ENLITT_CLIENT_ID } } }. It reports whether each variable is present, never its value.

business info

npx enlitt business info [--from <date>] [--to <date>]

Output: { business, earnings, payout, traffic: { usage }, range, data_fresh_at, application_count }. earnings.earnings_nano_usd is the balance you can be paid now, and payout is today's eligibility; neither is limited to the window. The fields are explained in Business reporting. In words, it states earnings, whether a payout is possible, and, when not, why (blocked_reason) and when it next can be (next_eligible_at).

traffic

npx enlitt traffic [--app <id>] [--days <n> | --from <date> --to <date>]

Output: { range, usage, days: [{ date, visitors, standard_requests, premium_requests, premium_earnings_nano_usd }] }, one row per day, with zeros for a day with no calls. With --app, each day also has standard_used_nano_usd and premium_used_nano_usd, and usage is that application's total.

Visitors are distinct signed-in users who made at least one call that UTC day. The same person on two days counts on both, so summing days does not give unique visitors for a week or month, and no command reports a unique count over a range. Report the daily figures, or say "visitor-days" for a sum. Business-wide visitors are not the sum of the per-application counts either.

app list

npx enlitt app list prints { applications: [{ id, name, environment, status, client_id, active_key_count }] }.

app show

npx enlitt app show [<id>] prints one application. The ID defaults to the one linked in enlitt.json; without a link it fails with project_not_linked.

{
  id: string;
  client_id: string;            // public; ENLITT_CLIENT_ID
  name: string;
  environment: "test" | "live";
  status: string;               // "active" when sign-in works
  info: { icon_url?: string; description?: string } | null;
  redirect_uris: string[];      // callback URLs, matched exactly
  allowed_origins: string[];
  created_at: string;
  api_keys: ApiKeyMetadata[];   // see key list
}

app create

npx enlitt app create --name <n> --environment test|live [options]

Prints the application, as app show does.

app update

npx enlitt app update [<id>] [options]. The ID defaults to the linked application. Only the lists and fields you name change.

Mixing a replace form with an add or remove form for one list is a usage error. A change takes effect at the next sign-in and signs no one out. The linked enlitt.json is updated to match.

key list

npx enlitt key list [--app <id>] [--scope app|read-only]

Output: { keys: ApiKeyMetadata[] }. Never a secret.

interface ApiKeyMetadata {
  id: string;
  name: string;
  prefix: string; // first characters of the secret, to recognize it
  scope: "model" | "reporting"; // wire values: "model" is an App key, "reporting" a Read-only key
  application_id: string | null; // null for a Read-only key
  environment: "test" | "live" | null;
  status: "active" | "revoked" | "expired";
  created_at: string;
  expires_at: string | null; // set on a rotated-out key: when it stops working
  last_used_at: string | null;
}

key create

npx enlitt key create (--app <id> | --scope read-only) --name <n> --write-env <file> [--replace] [--var <NAME>]

Output: { key: ApiKeyMetadata, secret_written_to: { file, variable }, gitignored }. Without --write-env or --reveal it refuses with secret_destination_required before any request, so no key is created that nobody captured. Needs a fresh approval.

key rotate

npx enlitt key rotate <key_id> --write-env <file> [--var <NAME>] [--confirm]

Same destination flags as key create, with one difference: --replace is on by default, because replacing the old value is the point. Rotation keeps the key's ID, name, type, and application, and issues a new secret. The old secret keeps working until previous_key.expires_at. A live App key and every Read-only key need --confirm. Needs a fresh approval. Output: { key, secret_written_to, gitignored, previous_key }.

key revoke

npx enlitt key revoke <key_id> --confirm disables a key immediately and permanently; calls with it fail at once. Always needs --confirm and a fresh approval. Output: { revoked: ApiKeyMetadata }.

setup

npx enlitt setup [options] wires a project in one step and is safe to rerun.

It runs these steps in order:

1. Resolve the application: --app, else the one in enlitt.json, else create one from the flags. When the application already exists, the creation flags (--name, --environment, --redirect-uri, --origin) are ignored, and stderr says so. Use app update to change an existing one.
2. Write enlitt.json.
3. Write ENLITT_CLIENT_ID to the env file.
4. Against staging, also write ENLITT_BASE_URL, so the SDK calls the same deployment.
5. If the env file has no ENLITT_SECRET_KEY, or with --replace-secret, create an App key named cli setup <date> and write it.

An existing secret is never rotated or overwritten without --replace-secret. Output: { application: { id, name, environment, client_id }, env_file, wrote, missing, gitignored, project_file, next }. wrote lists the variable names written, never values. missing lists what setup could not write with your role, each with an action; it is [] for the owner. next is the docs page to read next. Creating the key needs the owner role and a fresh approval.

doctor

npx enlitt doctor [--app <id>] [--env-file <file>] [--callback-url <url>]…

Output: { ok, findings: [{ code, severity, message, action }] }. Exits 1 when any finding is an error. It reads the secret only to compare it locally and never prints it.

Doctor findings

Checks run in this order. A check that depends on a failed one is skipped, so fix the first finding and run doctor again.

Errors and their actions

With --json an error is { "error": { "code", "message", "action" } }. Without it, stderr gets error: <message> and next: <action>. Do what action says; its commands already carry your --env.

Any other code: see Errors and recovery.

enlitt.json and the env file

enlitt.json sits at your project root (the nearest folder with a package.json or .git):

{
  "applicationId": "…",
  "environment": "test",
  "redirectUris": ["http://localhost:3000/auth/enlitt/callback"],
  "allowedOrigins": ["http://localhost:3000"],
  "envFile": ".env.local"
}

It records what the project expects and never holds a secret, so it is safe to commit. doctor compares it with what Enlitt has registered, and app update keeps it in sync.

The env file gets at most these variables:

The file must stay inside the project. The CLI refuses a file that git tracks. For an untracked file that git does not ignore, it adds the file to .gitignore and reports gitignored: true. Every other line of the file is kept unchanged. The file is written with owner-only permissions. Your deployed server needs the same variables in its own secret storage; the CLI writes only local files.

Where the credential lives, and how to revoke it

The CLI stores its sign-in in cli-<env>.json in ~/.config/enlitt (or $XDG_CONFIG_HOME/enlitt; %APPDATA%\enlitt on Windows), readable only by you. It is a CLI credential, not a browser session. Within your role, it can read the business, its applications and traffic, and manage applications and keys. It cannot do the things listed under What the CLI cannot do.

Revoke it with npx enlitt logout. You can also revoke it under Settings, CLI access in the business dashboard, which works for a machine you no longer have. Removing a member from the business stops their CLI sign-in at once.

Secret rules

• A raw API key is written only to the file you named. It never appears on stdout or stderr, in JSON, in enlitt.json, in an error, or in a log.
• --reveal prints a secret in human output only. It is refused with --json and whenever stdout is not a terminal, so an agent's shell cannot use it.
• Do not paste a key into a chat, an issue, or a commit.

What the CLI cannot do

The following are dashboard-only. The server refuses them to a CLI sign-in even if you hold the owner role:

• payouts and payout onboarding;
• members and invitations;
• ownership transfer;
• business creation;
• account settings.

--confirm is the only confirmation. There is no prompt, so the rule is the same with and without a terminal.