Wizard

CLI flags, device-flow auth, host referee, env policy, frameworks, source-map upload, statuses, env vars, and debugging.

The wizard is the supported CLI installer: it authorizes a project in the browser, detects your framework, preinstalls the install-sdk skill, runs an agent pass with host acceptance checks, and writes a local install report.

User-facing walkthrough: Install with the wizard.

Command

npx @humanbehavior/wizard

Pinning latest is also valid with npx:

npx @humanbehavior/wizard@latest

CLI help text documents the unpinned form. Runtime package installed into apps: humanbehavior-js@latest.

CLI flags

Flag	Purpose
`--project <slug>`	Use a specific project (also passed into the authorize URL)
`--install-dir <path>`	Install into another directory (default: cwd / `HB_TARGET_CWD` / `INIT_CWD`)
`--integration <name>`	Force framework: `nextjs` \| `nuxt` \| `vue` \| `remix` \| `svelte` \| `angular` \| `astro` \| `gatsby` \| `react` \| `html`
`--dashboard-url <url>`	Override dashboard origin (trailing slash stripped)
`--no-open`	Do not open the browser for device-flow approve
`--no-install`	Stop after authorization; skip code changes
`--dry-run`	Run without applying installs
`--verbose` / `-v`	Verbose logging
`--help`	Show help
`--`	Pass remaining args through to the agent

Source maps subcommand

npx @humanbehavior/wizard upload-sourcemaps [dir] --release <r> --api-key <k>

See Source maps.

Framework detection

Only framework-specific interactive question in the host today: Next.js App Router vs Pages Router when both/neither app/ and pages/ signals are ambiguous.

Per-framework leaf init: Frameworks.

Pipeline

Create wizard session against the dashboard API.
Device-flow Approve in the browser (unless local unattended env vars are set).
Host detects framework candidates (or uses --integration).
Host preinstalls the install-sdk skill.
Agent runs a single pass + revise checks.
Host acceptance gate may downgrade false success.
Host reports status back to the dashboard session.
Host writes humanbehavior-install-report.md in the install dir.

Host acceptance (why “success” is not trusted blindly)

Hard-fail examples:

Unsupported project shape
Bad init signature (e.g. object-form init({ apiKey }) or forbidden provider patterns)
Empty API keys
Wrong install target
Env policy violations

Soft path: structural wiring present but checks failed → needs-attention.

Init contract (what the wizard accepts)

Allowed	Forbidden
`HumanBehaviorTracker.init(apiKey, options?)`	Object-form `init({ apiKey })`
`init(apiKey, ingestionUrl?, options?)`	Wrapping App Router roots with `HumanBehaviorProvider` when the leaf pattern is required
React SPA: `HumanBehaviorProvider` with `apiKey` + `options.ingestionUrl`	`endpoint=` prop on the provider

HumanBehaviorTracker.init starts the tracker internally — wizard refs do not call .start() again.

Security policy

Direct filesystem/Bash access to .env* is denied. Use wizard env tools only.

Env vars (host / agent)

Var	Purpose
`HB_WIZARD_MODEL`	Model override (default `claude-sonnet-4-6`)
`HB_WIZARD_MAX_TURNS`	Turn budget (default 75)
`HB_WIZARD_ANTHROPIC_API_KEY`	Local Anthropic key for benchmarks / debugging
`HB_WIZARD_DEBUG`	Set to `1` for verbose wizard logs
`HB_WIZARD_STOP_REMARKS`	Optional debug remarks (`1` to enable)
`HB_DASHBOARD_URL`	Dashboard origin override (default `https://humanbehavior.co`)
`HB_INGESTION_URL`	Ingestion base override
`HB_TARGET_CWD` / `INIT_CWD`	Install directory fallbacks when `--install-dir` omitted

Read humanbehavior-install-report.md in the target app.
Confirm Network shows /api/ingestion/events and /api/ingestion/heartbeat after a rebuild with public env vars (init is not required).
Cross-check framework leaf placement: Frameworks.
See Install failures and No data.