Home CLI guides Auth CLI

Auth CLI

Last updated on May 07, 2026

Purpose

The Auth CLI exposes Firebase Authentication user administration through the same AuthListService used by the macOS app. It supports emulator projects by default and supports live Firebase projects when a bearer token is supplied.

All successful commands print JSON. Failures return exit code 1 with a readable error on stderr.

Project Setup

project connect --name Local --project-id demo-firestruct --environment emulator --host localhost --port 8080 --auth-port 9099
project select Local

Options shared by Auth commands:

  • --project <name|firebaseProjectID|uuid> overrides the selected project.
  • --authorization "Bearer <token>" supplies a live-project authorization header.
  • --access-token <token> is shorthand for --authorization "Bearer <token>".

For emulator projects, Firestruct sends the emulator admin authorization header automatically.

List Users

auth list --limit 100
auth list --limit 100 --page-token <nextPageToken>
auth list --filter alice --sort-by email
auth list --sort-by createdAt --descending

Options:

  • --limit defaults to 1000 and must be between 1 and 1000.
  • --page-token requests a specific Firebase Auth page.
  • --filter applies a client-side substring filter across UID, email, phone, and display name.
  • --sort-by accepts uid, email, phoneNumber, createdAt, or lastLoginAt.
  • --descending reverses the sort order.

Output contains project, users, nextPageToken, and logs. Each user includes profile fields, disabled and email verification state, custom claims JSON, metadata timestamps, password hash/salt when returned by Firebase, linked provider IDs, and provider details.

Search And Get

auth search --uid auth_alice
auth search --email alice@example.test
auth search --phone +15555550123
auth get --uid auth_alice

auth search and auth get use the Identity Toolkit lookup endpoint. Provide one of --uid, --email, --phone, or --search.

Create User

auth create --uid auth_alice --email alice@example.test --password secret
auth create --email alice@example.test --display-name "Alice" --email-verified true
auth create --uid auth_alice --custom-claims '{"role":"admin"}'

Supported fields:

  • --uid
  • --email
  • --password
  • --phone
  • --display-name
  • --photo-url
  • --disabled true|false
  • --email-verified true|false
  • --custom-claims '<json object>'

Update User

auth update --uid auth_alice --display-name "Alice Updated"
auth update --uid auth_alice --disabled true
auth update --uid auth_alice --email-verified false
auth update --uid auth_alice --custom-claims '{"tier":"pro"}'
auth update --uid auth_alice --delete-password

--uid is required. The other fields match auth create. Custom claims are validated by the core Auth service before the request is sent.

Bulk Enable, Disable, And Delete

auth disable --uid auth_alice --confirm
auth enable --uids auth_alice,auth_bob --confirm
auth delete --uid auth_alice --confirm
auth delete --uids auth_alice,auth_bob --confirm

Bulk mutation commands require --confirm. --uid targets one user, and --uids accepts a comma-separated list.

Output includes a task object with queued/running/success lifecycle fields, processed and total operation counters, attempt count, duration, and any retained error description.

Export Users

auth export --format json --output build/auth-users.json
auth export --format csv --output build/auth-users.csv
auth export --search alice@example.test --output build/alice.json
auth export --uids auth_alice,auth_bob --fields uid,email,customClaims --output build/auth-users.json

Options:

  • --format json|csv defaults to json.
  • --output <path> is required.
  • --search <text> exports lookup results instead of all users.
  • --uid or --uids narrows the exported all-user result.
  • --page-size controls all-user pagination and defaults to 1000.
  • --fields <comma-separated AuthExportField names> selects export fields.
  • --no-metadata omits metadata fields.
  • --no-custom-claims omits custom claims.
  • --include-hashes includes password hash and salt when Firebase returns them.
  • --delimiter <char> sets CSV delimiter.
  • --json-structure array|keyedByUID|envelope controls JSON shape.
  • --timestamps iso8601|unixMilliseconds|unixSeconds controls timestamp encoding.

Output includes export counts, destination metadata, logs, and the completed task snapshot.

Import Users

auth import --file auth-users.json --format json --confirm
auth import --file auth-users.csv --format csv --uid-column uid --confirm
auth import --file auth-users.json --update-existing --confirm

Options:

  • --file <path> is required.
  • --format json|csv defaults to json.
  • --delimiter <char> sets CSV delimiter.
  • --no-header treats CSV as headerless.
  • --uid-column <name> defaults to uid.
  • --update-existing updates users when create returns an already-exists error.
  • --confirm is required.

JSON imports accept either an array of user objects or an object keyed by UID. CSV imports require a UID column unless --no-header is used.

Output includes imported count, logs, and the completed task snapshot.

Transfer Users

auth transfer --target Staging --confirm
auth transfer --target Production --uids auth_alice,auth_bob --confirm
auth transfer --target Staging --delete-source --confirm

The selected or --project project is the source. --target accepts the target project name, Firebase project ID, or UUID. Transfer exports users from the source, creates or updates them in the target, and optionally deletes source users with --delete-source.

For live-to-live or emulator-to-live transfer, use target-specific credentials when needed:

auth transfer --target Production --access-token <source-token> --target-access-token <target-token> --confirm

Output includes transferred count, optional source deletion count, logs, and the completed task snapshot.

JavaScript Auth Scripts

auth run --file scripts/auth-report.js
auth run --script 'async function run(ctx, admin) { const r = await admin.auth().listUsers(100); return r.users.map(u => ({ uid: u.uid, email: u.email })); }'

auth run loads all Auth users first, injects them into the local JavaScript runtime as admin.auth() data, and returns structured documents, raw runtime JSON, and logs. The Auth shim supports common Admin Auth methods such as listUsers, getUser, getUserByEmail, getUserByPhoneNumber, getUsers, createUser, updateUser, deleteUser, deleteUsers, setCustomUserClaims, token helpers, and email link helpers.

Options:

  • --file <path> reads a script from disk.
  • --script <text> runs an inline script.
  • --timeout <seconds> defaults to 15.

Script mutations run against the local runtime snapshot, not Firebase. Use auth create, auth update, auth delete, auth import, or auth transfer for Firebase mutations.

Run Through Selected Module

module select auth
run list --limit 100
run export --output build/auth-users.json

run dispatches Auth actions when the selected CLI module is auth.

Current CLI Gaps

The GUI Auth module still has a few workflows that are not first-class CLI commands:

  • Auth-to-Firestore linked-user navigation.
  • Storage-backed profile photo upload picker.
  • Saved Auth query/script presets.
  • Persistent task history across separate CLI invocations.

Source Anchors

  • Sources/FirestructCLIKit/AuthCommand.swift
  • Sources/FirestructCLIKit/FirestructCLI.swift
  • Sources/FirestructCore/AuthListService.swift
  • Sources/FirestructCore/AuthListService+Operations.swift
  • Tests/FirestructCLIIntegrationTests/FirestructCLIIntegrationTests.swift