Overview
The base-idp CLI — scaffold projects, register apps, test connectivity, and decode tokens straight from your terminal.
The base-idp CLI ships with the TypeScript SDK and runs through npx. There
is nothing to install globally. You do not even need to be inside a Node
project — npx downloads the package on demand and runs it.
The CLI has four commands and they cover the things you actually do when integrating Base IdP: scaffold a starter, write an env block, check connectivity, and look inside a token.
The four commands
create
Scaffold a wired starter for your stack. Picks the right env per role, writes the SDK glue.
init
Print the minimal env block for your client. Can also register the app in one step.
test
Hit Base IdP's health and discovery endpoints. Confirms network and client id.
token
Decode a PASETO token and print its header, footer, and claims.
Running it
npx base-idp <command> [options]The first invocation downloads the package; subsequent invocations are
instant. If you want to pin a version, use the package@version form.
npx base-idp@latest create
npx base-idp@1.1.0 test --client-id sq_live_yourappIf you would rather install the CLI globally (you ship a lot of new apps and
the npx startup gets annoying), it is the same package.
npm install -g base-idp
base-idp create --stack flutter --client-id sq_live_yourappGetting help
Every command prints its own usage when called with help or no arguments,
and the top-level help lists every command and option.
npx base-idp helpUsage:
base-idp create [--stack <id>] [--client-id <id>] Scaffold a wired starter for your stack
base-idp init [--client-id <id>] [--key <key>] Generate env config
base-idp test [--issuer <url>] [--key <key>] Test IdP connectivity
base-idp token <token> Decode and inspect a PASETO tokenA typical session
The first time you integrate a new app, the CLI handles most of the work in this order.
# 1. Scaffold a wired starter for your stack.
npx base-idp create --stack nextjs-fullstack --client-id sq_live_web \
--client-secret sqk_your_secret
# 2. Confirm the registration is live.
npx base-idp test --client-id sq_live_web
# 3. Later, when a token does not behave, look inside it.
npx base-idp token v4.public.eyJ...These four commands cover the integration lifecycle. Anything more complicated — issuing service tokens, rotating secrets, managing redirect URIs — happens in Square Experience Cloud, not in the CLI.