cli

name

cli

description

The Peek app CLI (@peektravel/app-cli) — the tool that connects your local app to the app registry: discovering commands, checking which registry you're on (production vs sandbox) and who you're logged in as, running the app locally behind a Cloudflare tunnel so it can be tested inside the platform App Store, and — most importantly — inspecting the **extensions** an app can declare in its manifest (how the registry talks to the app: the settings/embed URL, the install/uninstall webhook, and per-event booking webhooks). Use when running any `peek` / `npx @peektravel/app-cli` command, deciding whether a feature is feasible on a platform, wiring the manifest, or debugging "which registry / am I logged in / why is it prompting me." Triggers on "peek CLI", "app-cli", "peek dev", "sync-app", "extensions list", "extensions show", "show-env", "auth whoami", "auth login", "which registry", "production vs sandbox", "skip-env-confirm", "what extensions are available", "app_registry_settings_url", "app_registry_webhook", "webhook_on", "app_registry_mcp_url", "extensions list no output", "exit 255", "headless", "not signed in".

The Peek app CLI

@peektravel/app-cli (invoked as peek when installed, or npx @peektravel/app-cli@latest otherwise) is the bridge between your local app and the app registry. It scaffolds apps, runs them locally against the registry, pushes the manifest, and — the part you'll reach for most while designing a build — tells you which extensions the registry offers, so you can check a feature is even possible before you plan it.

This skill is the generic map of the CLI. Concrete manifest/registry details for your platform live in manifest-and-deploy (and your platform's *-manifest-and-deploy); this skill is about driving the CLI itself.

Keep this skill honest against the installed CLI. Command names, flags, and extension slugs evolve. This skill is the durable shape; for the exact current surface, run --help and extensions list/extensions show (below) rather than trusting memory. If something here disagrees with the live CLI, the live CLI wins.

0. Get the latest CLI, then discover what it can do

1. Always run the latest. npx caches by version, so pin @latest to force a fresh resolve:

   npx @peektravel/app-cli@latest --version
   

   (If you have it installed globally as peek, npm i -g @peektravel/app-cli@latest first.)
2. Read the command list rather than assuming it — the CLI grows commands:

   npx @peektravel/app-cli@latest help
   

   peek <command> --help shows a single command's flags.

1. Two preflight checks before anything touches the registry

Every registry-touching command (dev, sync-app, use-url, extensions *, auth *) depends on two bits of state. Check both up front so you're not debugging a 401 or a surprise prompt later.

a. Which registry am I on? — show-env

npx @peektravel/app-cli@latest show-env

Tells you whether the CLI is pointed at the production registry or a sandbox/override. You should almost always be on production. If it reports an override and you didn't intend it, reset:

npx @peektravel/app-cli@latest set-env --clear

Avoid the interactive override prompt. When you're on a non-production registry, every command stops to ask "Continue against this registry?" — which stalls any non-interactive/agent run. Append --skip-env-confirm to auto-confirm for that invocation:

npx @peektravel/app-cli@latest sync-app app.peek.json --skip-env-confirm

It's a per-invocation flag — add it to every command you run while an override is active.

b. Am I logged in? — auth whoami

npx @peektravel/app-cli@latest auth whoami

Shows the signed-in account and its registry. If it says you're not signed in, the user must log in (it opens a browser flow — you can't do it for them):

npx @peektravel/app-cli@latest auth login

Sign in before running any registry command headless. Every registry-touching command (extensions list/show, sync-app, dev, …) calls an "ensure logged in" gate that, when you're not signed in, auto-starts the browser login flow. In a non-interactive / agent shell that flow can't complete — the command emits no output and exits 255 (it isn't broken; it's silently waiting on a browser that never opens). So run auth whoami first; if it says not-signed-in, have the user run auth login in an interactive terminal, then re-run your command. This is the #1 cause of "extensions list printed nothing / exit 255."

2. Run the app locally — dev

npx @peektravel/app-cli dev

dev does three things at once: runs the app locally, opens a public Cloudflare tunnel to it, and registers that tunnel URL with the app registry — so the local build can be installed and tested inside the platform's App Store with real auth. This is the only way to exercise the embedded app for real; a plain framework dev server can't (no host frame, no token — see app-builder "Running the app"). You can't run this yourself — it needs the user's credentials — so hand off to the user when it's time to see the app run. What dev does to the manifest (it creates a separate test app / app-dev.json and writes .env.local) is a manifest-and-deploy concern.

3. Extensions — how the registry talks to the app

Extensions (a.k.a. extendables) are the contract between the registry and your app. An app declares the extensions it uses in its manifest — app.<platform>.json (e.g. app.peek.json), one manifest per platform. Running:

npx @peektravel/app-cli sync-app app.peek.json

pushes that manifest to the registry, activating the declared extensions. Extensions are the entry points and event hooks that make the app do anything the platform surfaces.

List what's available — extensions list

npx @peektravel/app-cli@latest extensions list                 # all platforms
npx @peektravel/app-cli@latest extensions list --platform peek # scope to one platform
npx @peektravel/app-cli@latest extensions list --json          # machine-readable

Check this during design. What's available differs per platform — a feature that leans on an extension one platform offers may be impossible on another. Treat extensions list --platform <platform> as part of the feasibility / capability gate (see app-builder): if the extension a plan needs isn't listed for the selected platform, the plan won't ship — flag it to the user rather than assuming it exists.

The extensions to know

• app_registry_settings_url@v1 — the URL the registry loads for the app's settings page, which is the main app page the user sees after installing. This is the app's key entry point — almost every app declares it. It's the embed URL the platform POSTs to (see embed-and-auth).
• app_registry_webhook@v1 — declare this if the app stores any local data. It notifies the app when a user hits install (so you can provision eagerly instead of waiting for their first visit) and when they uninstall. The uninstall signal is critical: you're expected to wipe all of that install's data on uninstall (see backoffice-data, webhooks).
• webhook_on_…@v1 — the family of booking-system event webhooks the app can subscribe to, to be notified when something happens (a booking created/changed/cancelled, etc.). These are the inbound-event path — how you build reactive features. See webhooks for the handling model.
• app_registry_mcp_url@v1 — declares the app's MCP endpoint so the store's AI orchestrator can drive it headlessly. One parameter, mcp_url (the route Peek calls). Declare it when the app exposes MCP tools — see mcp-endpoint.

Get the config for one — extensions show

Each extension has its own required parameters and configuration for the manifest. Don't guess the shape — read it live:

npx @peektravel/app-cli@latest extensions show app_registry_settings_url@v1
npx @peektravel/app-cli@latest extensions show app_registry_webhook@v1 --json

extensions show <slug> lists the extension's type, the platforms it's available on, and its configurable fields — i.e. exactly what to put in app.<platform>.json. Use it whenever you wire a new extension into the manifest.

Hard rules

• Confirm you're on production and logged in (show-env, auth whoami) before registry work; reset a stray override with set-env --clear.
• Add --skip-env-confirm to every command while a non-production registry is active, so the override prompt never stalls a run.
• Verify extensions exist for the SELECTED platform (extensions list --platform <platform>) while judging feasibility — availability is platform-specific. Flag any gap to the user.
• Declare app_registry_webhook@v1 and wipe data on uninstall whenever the app persists data.
• Read extensions show <slug> for the manifest config — don't hand-write extension params from memory.
• You can't run dev or auth login for the user — they need the user's credentials/browser. Hand off.

Related skills

• app-builder — the build workflow this CLI serves; the capability gate and "Running the app" (why dev is the only real way to exercise the embed).
• manifest-and-deploy (+ your platform's *-manifest-and-deploy) — what the manifest declares, the two-app/two-environment split, and what dev / sync-app do to it.
• embed-and-auth — the settings/embed URL (app_registry_settings_url@v1) is the route the registry POSTs to.
• webhooks — handling the events app_registry_webhook@v1 and webhook_on_… deliver.
• backoffice-data — per-install data scoping and the wipe-on-uninstall obligation.