🔥 appcheck-debug-token

Register Firebase App Check debug tokens from the command line.

The thing the Firebase CLI forgot to build.

---

Running your app on a simulator with App Check enforced? Then your backend keeps rejecting it with 401 / App attestation failed — because the simulator can't do App Attest and its debug token isn't registered.

The fix lives in the Firebase Console, buried under App Check → Apps → Manage debug tokens. There is no firebase CLI command for it. So you click. Every. Single. Time a teammate or CI machine spins up a new simulator.

appcheck-debug-token makes it one line:

$ appcheck-debug-token add -p my-project -b com.example.app

• Checking gcloud auth…
✓ gcloud access token acquired
• Resolving project 'my-project'…
✓ Project: my-project (number 1234567890)
✓ App Check API enabled
✓ Resolved app: 1:1234567890:ios:abc123def456
✓ Access OK (3 existing token(s))
• Relaunching com.example.app to force the token to print…
✓ Extracted token from logs
✓ Token format valid: 1B2C3D4E-5F60-7182-9304-0011223344FF
• Registering 'my-mac-20260619-0930' on 1:1234567890:ios:abc123def456…
✓ Registered (resource: a1b2c3d4e5f6)
• Verifying…
✓ Verified — 'my-mac-20260619-0930' is registered. App Check calls now pass.

No token to copy-paste. No console. No dashboard. ✨

---

✨ Features

• 🧩 Works for any project & app — project id or number, app id auto-resolved.
• 🤖 Zero copy-paste — pulls the debug token straight from a booted iOS Simulator's logs.
• 🧪 Three verbs — list, add, delete. Plus --dry-run for a no-op rehearsal.
• 🛟 Safe by design — sanity-checks every step (auth, project, API, permissions, token format) and verifies the write by reading it back.
• 📦 No dependencies — pure Python standard library. One file.
• 🎨 Readable output — colored, step-by-step, machine-friendly (token on stdout).

📋 Requirements

Tool	Why	Needed when
Python ≥ 3.8	runs the script	always
gcloud (authenticated)	calls the App Check API	always
firebase-tools	resolves the app id	only if you omit --app
Xcode (xcrun)	reads the token from a Simulator	only if you omit --token

You need Firebase App Check Admin on the project. Authenticate once with gcloud auth login.

🚀 Install

Recommended — pipx (isolated, global command):

pipx install git+https://github.com/bogdanmatasaru/appcheck-debug-token

With pip:

pip install git+https://github.com/bogdanmatasaru/appcheck-debug-token

Or just grab the file — it has no dependencies:

curl -O https://raw.githubusercontent.com/bogdanmatasaru/appcheck-debug-token/main/appcheck_debug_token.py
chmod +x appcheck_debug_token.py
./appcheck_debug_token.py --help

⚡ Quick start

# 1. See what's already registered (read-only)
appcheck-debug-token list -p my-project

# 2. Add the debug token of a running simulator (auto-detected + relaunched)
appcheck-debug-token add -p my-project -b com.example.app

# 3. Clean up later
appcheck-debug-token delete -p my-project -n my-mac-20260619-0930

📖 Usage

appcheck-debug-token <command> -p <project> [options]

Commands:
  list      List the project's App Check debug tokens (read-only).
  add       Register a debug token.
  delete    Delete a debug token by display name.

Shared options:
  -p, --project    GCP/Firebase project id OR number          (required)
  -a, --app        Firebase App ID (1:NUM:ios:HEX) — auto-resolved if omitted
      --platform   ios | android | web   (default: ios)
      --dry-run    Run all checks but make no changes

add options:
  -t, --token      Debug token UUID — auto-extracted from a simulator if omitted
  -n, --name       Display name (default: <host>-<UTC date>)
  -b, --bundle     Bundle id to relaunch on the simulator to print the token
  -u, --udid       Simulator UDID (default: the booted one)

delete options:
  -n, --name       Display name of the token to delete        (required)

Examples

# Explicit token + friendly name
appcheck-debug-token add -p my-project -t 1B2C3D4E-5F60-7182-9304-0011223344FF -n "Alice's M3"

# Pick a specific simulator + a specific app
appcheck-debug-token add -p 1234567890 -a 1:1234567890:ios:abc123 -u <UDID> -b com.example.app

# Rehearse without writing anything
appcheck-debug-token add -p my-project -b com.example.app --dry-run

🔑 Where does the debug token come from?

On the Simulator, Firebase prints it to the console at launch:

[Firebase/AppCheck] Firebase App Check debug token: '1B2C3D4E-5F60-7182-9304-0011223344FF'.

• Pass --bundle <id> and the tool relaunches the app and grabs it for you.
• Or copy it once and pass --token.
• The token persists per simulator install, so you register it once.

💡 Physical devices don't need this — they use App Attest, which attests automatically. Debug tokens are a Simulator thing.

🔧 How it works

gcloud auth print-access-token ─┐
                                ├─►  POST  firebaseappcheck.googleapis.com
firebase apps:list (app id)  ───┘        /v1/projects/<num>/apps/<app>/debugTokens
xcrun simctl log show (token) ──┘

It resolves your project number + app id, ensures the App Check API is enabled, checks you actually have access, validates the token, registers it, then reads it back to confirm. The required X-Goog-User-Project quota header is sent for you (the usual cause of a mysterious 403).

🩺 Troubleshooting

Symptom	Fix
Not authenticated	gcloud auth login
403 Forbidden	Your account needs Firebase App Check Admin on the project.
requires a quota project	Handled automatically — but ensure your project id is correct.
No debug token in the last 5m of logs	Launch the app on the simulator (or pass --bundle / --token).
Multiple ios apps	Pass --app <id> to disambiguate.
App still rejected after adding	Make sure the simulator app actually uses that token (it's printed at launch), and that you registered it under the right app id.

🤝 Contributing

Issues and PRs welcome! It's a single, dependency-free file — easy to hack on.

📄 License

MIT © Bogdan Matasaru