CLI reference
The npx @north-light/sdk commands for scaffolding an app, writing its signing key and environment file, and installing the agent skill.
npx @north-light/sdk <command> runs the package's one command-line tool. Run it with no command, or with --help, to print the list below. An unknown command prints the list and exits 1.
| Command | What it does | Needs crtr |
|---|---|---|
npx @north-light/sdk init [dir] [--agent claude|agents|all] [--global-skill] | Scaffold a Northlight app in an empty or new directory (server.ts, key, env file, skill), or add the SDK, a key and the skill to an existing project. Never overwrites a file. | No |
npx @north-light/sdk skill [--agent claude|agents|all] [--global] [--print] | Write the packaged northlight skill into .agents/skills and .claude/skills (or ~/ with --global), replacing an older copy. --print writes it to stdout. | No |
npx @north-light/sdk keygen [--out <path>] [--app <client id>] [--yes] | Write a private signing key to local/app-key.json (mode 0600) and print the public JWK to register. | Only with --app |
npx @north-light/sdk env --client-id <client id> [--origin <url>] [--issuer <url>] [--out <path>]npx @north-light/sdk env --app <client id> [--out <path>] | Write CROUTER_ISSUER, CROUTER_CLIENT_ID and APP_ORIGIN into local/app.env, keeping every other line. --client-id makes no network call; --app reads them through crtr. | Only with --app |
keygen and env are the only commands that can call crtr, and only with --app. The documented path on this site never uses --app, so you do not need crtr.
Details
init
In an empty or new directory it writes package.json (with @north-light/sdk pinned to the CLI's own exact version, plus tsx), server.ts (the quickstart server), .gitignore (local/, node_modules/) and local/app.env, and runs keygen into local/app-key.json. It installs the skill. Then it prints the public JWK, the console URL https://account.northlight.ai/console/new, the values to type, and npx @north-light/sdk env --client-id <client id> as the next step.
In a directory that already has a package.json it writes no app code. It runs npm i --save-exact @north-light/sdk@<its own version>, runs keygen unless local/app-key.json exists, and installs the skill.
It never overwrites a file. On a refused step it exits non-zero and names the file it refused.
skill
Writes the northlight Agent Skill that ships in the package, replacing an older copy. --agent picks .claude/skills, .agents/skills or both. --global writes under your home directory instead of the project. The skill's metadata.sdk-version is the package version, so run skill again after you change the pinned SDK version.
keygen
Writes a private signing key to local/app-key.json with mode 0600, refuses to overwrite an existing file (pass --out for another path), and prints the public JWK on stdout. Register the JWK in the console with Add key on the app's Sign-in tab, or paste it under Register an app. With --app <client id>, it offers to add the key to your app through your own crtr (crtr cloud apps keys add); --yes skips the question. This needs a joined crtr, which this site does not otherwise require.
env
env --client-id <client id> writes CROUTER_ISSUER (default https://account.northlight.ai), CROUTER_CLIENT_ID and APP_ORIGIN (default: the existing value in the file, else http://localhost:3000) into local/app.env. It keeps every other line and makes no network call. --out <path> writes another file. env --app <client id> reads the same values through crtr instead. Passing both --client-id and --app is a usage error.