Scan a codebase, instrument it with Holostaff tracking, and embed a copilot — all from your terminal.
$ holostaff
Welcome to Holostaff. Looks like a Vue 3 + Vite app with 14 components and 13 routes.
> /scan
✓ Scan complete · 183.1s · TutorLM
Send to your Holostaff workspace? [Y/N/S]
Alpha. The flows in this README work end-to-end against the deployed Holostaff API. Distribution is a private install for now; public npm + signed releases are pending the A8 milestone.
The @holostaff/sdk tracking package referenced by /instrument is not yet on npm — /instrument ships the integration shape; the package lands separately. Same caveat for holostaff-widget is not — that one is published.
# From npm:
npm install -g @holostaff/cli
# Or from source:
git clone https://github.com/Holostaff-AI/holostaff-cli
cd holostaff-cli
npm install
npm run build
npm linkRequires Node 20+.
In a repo you want to add a copilot to:
$ cd ~/code/your-app
$ holostaffThe interactive shell walks you through:
- Sign in. Device-flow OAuth via your Holostaff workspace. Browser opens; you confirm.
/scan. Reads your code (read-only), produces a structured knowledge artifact, shows a trust report (what gets sent vs. what stays local), uploads on confirm./instrument. Drafts a patch that adds the Holostaff tracking SDK to your app. Shows a per-file diff. On confirm, creates aholostaff/instrument-<ts>branch and commits./embed. Same flow for the widget script tag./refine. Edits the artifact's identity (product name, description, notes) without re-scanning. Survives re-scans./help. Lists every slash command.
You can also chat the agent — anything that doesn't start with / goes to a free-form conversation.
| Command | Purpose |
|---|---|
/scan |
Scan this repo, produce + upload an artifact |
/scan --add-repo |
Pick an existing source to merge into (multi-repo product) |
/refine |
Edit identity overrides on the live artifact |
/instrument |
Generate Holostaff SDK init + tracking, commit to a branch |
/embed |
Add the widget script tag to the app entry, commit to a branch |
/whoami · /workspace · /login · /logout |
Auth + session utilities |
/help · /quit |
Help / exit |
| Command | Purpose |
|---|---|
holostaff |
Open the interactive shell |
holostaff login |
Re-run device-flow auth |
holostaff logout |
Clear local credentials |
holostaff whoami |
Show signed-in user + workspace |
holostaff workspace |
Show active workspace |
holostaff scan [--add-repo ID] [--quiet] [--json] [--out PATH] |
Headless scan + upload (CI-friendly) |
holostaff --version · --help |
Version / usage |
holostaff scan --quiet --json runs the full scan + upload without a TTY. Auth comes from env vars; result is a single JSON object on stdout.
export HOLOSTAFF_API_KEY="hsk_…" # workspace API key
export HOLOSTAFF_WORKSPACE_ID="workspace_…" # the workspace it's bound to
export AZURE_ANTHROPIC_ENDPOINT="…" # model API
export AZURE_ANTHROPIC_API_KEY="…"
holostaff scan --quiet --json --out artifact.json
test $? -eq 0 || exit 1
jq -r '.upload.viewUrl' artifact.jsonExit codes:
0uploaded successfully1scan or upload failed2bad args or preflight (missing env)3auth not configured for CI
/scan reads your source code with read-only tools, but the artifact it sends to your workspace contains only:
- Product identity: name, one-line description, framework, language
- Routes (paths + descriptions)
- Component names + roles
- Customer-facing copy strings (the literal text users see, with file/i18n locations)
- Brand voice (tone, keywords)
- Workflows (multi-step user flows + steps)
- Coverage gaps the scan flagged
Your source code, file contents (beyond the excerpted UI strings), .env files, secrets, and git history never leave your machine.
The trust report shows you exactly what's about to be sent before you confirm.
Two paths:
Interactive (default): OAuth-style device flow. Run holostaff and a browser opens to authorize. Credentials live in ~/.holostaff/credentials.json (mode 0600).
CI: Set HOLOSTAFF_API_KEY + HOLOSTAFF_WORKSPACE_ID in your environment. The CLI skips the file-based path when these are set.
Generate a workspace API key in the dashboard at Settings → CLI keys (lands in B3).
After your first successful upload, the CLI writes .holostaff/source.json in your repo. Subsequent scans bind to the same Holostaff source and version-bump its artifact.
Add .holostaff/source.json to your .gitignore if you don't want teammates' scans to land on your source automatically — multi-user shared bindings are a B3 follow-up.
| Var | Required | What |
|---|---|---|
HOLOSTAFF_API_KEY |
CI mode | Workspace API key (Bearer JWT) |
HOLOSTAFF_WORKSPACE_ID |
CI mode | Workspace this key is bound to |
HOLOSTAFF_API_BASE_URL |
optional | Backend URL override (default: prod) |
HOLOSTAFF_APP_BASE_URL |
optional | Dashboard URL for the result viewUrl (default: https://www.holostaff.ai) |
AZURE_ANTHROPIC_ENDPOINT |
scan / instrument / embed / refine | Foundry endpoint |
AZURE_ANTHROPIC_API_KEY |
scan / instrument / embed / refine | Foundry key |
Production CLI distribution will drop the BYO AZURE_* requirement — the backend will issue per-session model tokens. Tracked in PRD §13 OQ10.
Anonymous, opt-out. The CLI emits typed events for command starts, completions, and errors so we can see what's working and what's broken.
What's collected (per event):
cli_version,node_version,os- Hashed
workspace_id(SHA-256 — never the raw ID) command(scan/instrument/ etc.)duration_ms,outcomeframework_detected,repo_size_bucketerror_kindfor failures (typed:auth_expired,instrument_typecheck_failed,network_blocked, etc.)
What's never collected: file paths, source code, source content, secrets.
To disable: set HOLOSTAFF_TELEMETRY=0 in your environment.
Apache-2.0. See LICENSE.
PRs welcome — see CONTRIBUTING.md for dev setup, smoke spikes, and the release flow. Release notes live in CHANGELOG.md.
Open an issue at https://github.com/Holostaff-AI/holostaff-cli/issues or reach out via your Holostaff workspace's support channel.