cli-reference.md

CLI Reference

All commands run from your project root unless --cwd is specified.

--cwd is resolved relative to your current shell directory. If your shell is already inside the DNA project, omit --cwd or pass --cwd .. From a monorepo root, pass the path to the package that contains .DNA/ (for example packages/dna-cli).

Global

dna --help
dna --version

init

Initialise DNA in the current project.

dna init
dna init -y                    # non-interactive defaults
dna init --cwd /path/to/project

Creates .DNA/, DNA/Impressions/, Behaviour, neuralNetwork, CellularMemory, immune system, and AI tool files.

scan

Detect stack, dependencies, tests, CI, and risks.

dna scan
dna scan --cwd ./my-app
dna scan --open-pr          # when drift is critical, write sync plan

Includes an Impressions drift score when DNA is installed (missing docs, stack mismatch, stale CellularMemory).

lab

Production observability portal at /labs — Monitor (Overview, Issues, Events, Performance), Delivery (Releases, Source maps), Quality (Reports, Coverage, CI, APIs), Project (Doctor, Installs), and Intelligence (Impressions, Cellular Memory). APIs tab documents every Lab route (Description / Usage / Received / Sent). URL deep links: /labs/<tab>, /labs/issues/<id>. Sidebar sections stay independently open. Header Refresh disables + spins and reloads the active tab. Mobile (≤900px): off-canvas nav + sticky chrome. See Lab APIs reference v0.6.18, Lab Refresh UX v0.6.16, Lab upgrade DX, Lab analytics v0.6.14, and Lab UI Humaan parity v0.6.7.

dna lab install
dna lab serve
dna lab serve --port 3200
dna lab installs            # list nested/stale DNA installs
dna lab installs --fix     # upgrade every owner package to @latest
dna update                  # also aligns Lab installs (v0.6.16+) then prints restart steps
dna register lab --url https://your-app.example.com

After any Lab package bump: restart the API that mounts Lab, then hard-refresh /labs. Confirm with GET /api/dna/labs/health → dnaVersion.

Local: no login. Production: email + password + OTP after dna register lab pairing (paste Pairing ID + code at /labs; sign into the app if the host requires a session).

See Runtime Observer.

dashboard

Legacy alias — starts Lab at /labs on port 3200 (same as dna lab serve).

memory

Export, import, and sync CellularMemory segments across projects and team registries.

dna memory export --out .DNA/exports/memory.json
dna memory import .DNA/exports/memory.json --merge
dna memory import .DNA/exports/memory.json --on-conflict newest
dna memory sync
dna memory sync --registry <path>

Conflict strategies: newest (default), keep-local, keep-remote.

skeletor

When Skeletor is installed, DNA pulls the local fleet bridge by default and feeds it to AI (dna context, doctor → CellularMemory).

dna skeletor status     # detect install + bridge
dna skeletor feed       # write .DNA/CellularMemory/parietalLobe/skeletor-fleet.md
dna skeletor context    # print fleet markdown

Opt out in .DNA/config.dna.json:

{ "skeletor": { "enabled": false } }

Bridge file (written by Skeletor on full fleet scan): ~/Library/Application Support/app.humaan.skeletor/bridge/fleet.json

generate

Platform feature code scaffolds.

dna generate feature audit-logging
dna generate feature sso
dna generate feature multi-tenant
dna generate feature feature-flags
dna generate feature gradual-rollout

plan impressions-sync

Generate a plan to reconcile Impressions with the codebase when drift is detected.

dna plan impressions-sync
dna plan impressions-sync --open-pr

ivf shared-library

Shared library extraction for monorepos.

dna ivf shared-library --dry-run
dna ivf shared-library --scaffold
dna ivf shared-library --execute

recommend

Suggest architecture and stack from scan + description.

dna recommend
dna recommend --description "Multi-tenant B2B SaaS"

context

Generate AI-ready context for a target.

dna context cursor
dna context claude
dna context chatgpt
dna context copilot
dna context windsurf
dna context gemini
dna context backend
dna context frontend
dna context security
dna context qa
dna context devops
dna context multilingual
dna context all

multilingual loads language stem packs — bidirectional translation, sentiment, and localized documentation guidance.

validate

Validate project structure and Behaviour compliance.

dna validate

Exits with code 1 on errors.

watch

Watch filesystem changes and update CellularMemory.

dna watch

Runs until interrupted.

doctor

One-command onboarding — scaffolds DNA, CI, Docker, hooks, runtime storage, GitHub sign-in, and auto-wires middleware for Express, Fastify, and Next.js.

npx @superhumaan/dna-by-humaan doctor
npm install   # when package.json was updated

Report only (no fixes, no browser login):

dna doctor --check-only

credits

Show sponsors, funding links, and bundled package credits (also via npm fund @superhumaan/dna-by-humaan).

dna credits

update

Upgrade the DNA CLI, re-apply every installed knowledge pack, and force re-inject Cursor/Claude always-on rules (AGENTS.md, .cursor/rules/*, workbench skills, stems).

dna update
dna update --channel beta
dna update --check-only          # report only — no writes
dna update --skip-cli            # packs + rules only
dna update --skip-packs          # CLI + rules only
dna update --skip-workbench      # skip AI rule re-injection (not recommended)

dna update exits non-zero when AI injection verification fails (missing/stale always-on rules) or pack refresh fails — so agents cannot silently skip DNA.

runtime install

Write runtime integration snippets to .DNA/runtime/.

dna runtime install

feature

Start the feature factory from a plain-language request (optional — Cursor/Claude do this automatically in chat).

dna feature "I want providers to record phone calls and transcribe the notes"

Writes ai/feature-request.md, a baseline quality report in .DNA/reports/quality/, and continues in your AI tool.

quality

Local SonarQube-style code quality — no SonarQube server required. Runs automatically during feature factory.

quality report

dna quality report --feature          # feature-scoped gate (git-changed files)
dna quality report                    # full repository scan
dna quality report --paths src/foo.ts
dna quality report --feature --json   # machine-readable output

Writes .DNA/reports/quality/<slug>.md. Exits with code 1 when the gate fails (blocker or critical issues).

quality scan

Stdout-only scan without writing a report file.

dna quality scan --feature

docker

Docker build verification — scaffolded on dna init, required at feature factory close-out.

docker install

dna docker install
dna docker install --force

docker build

dna docker build
dna docker build --tag myapp:local

Exits with code 1 if Docker is unavailable or the build fails.

feature-factory install

Re-enable Cursor/Claude feature factory rules after uninstall.

dna feature-factory install

Enabled by default during dna init. DNA configures Cursor and Claude automatically — users describe features in plain language; agents run the factory without copy-paste prompts.

feature-factory uninstall

Remove feature factory files from the project (does not remove .cursor/rules/dna.mdc).

dna feature-factory uninstall

Re-enable with dna feature-factory install.

commands

Install DNA Workbench, AGENTS.md, 103 prompt stem packs, and /dna-* CLI slash commands (.DNA/stems/<id>/, .cursor/commands/, skills, always-on rules) by default on init, doctor, and update. Engineering work routes through the mandatory 9-role agent loop (ai/agent-loop.md). Strategy + product-intelligence + day-to-day operator stems (Golden Circle, canvases, diagnose/SWOT/competitors/upgrade leverage, admin/Tauri/fleet/PR/preview/audits) install with the same workbench path.

dna workbench install
dna stems list
dna stems show analyze-project
dna stems install
dna commands install    # refresh /dna-* CLI wrappers only
dna commands list
dna commands export-catalog --out .DNA/intelligence-catalog.json
dna commands uninstall

Installed automatically with dna init, dna doctor, and dna update (workbench + stems + /dna-* commands).

Copy-paste library: dna.humaan.app/intelligence

workbench

DNA Workbench — prompt-first Cursor and Claude packages. Installed by default on dna init, dna doctor, and dna update. DNA is always on — users do not need to say “use DNA”. AGENTS.md classifies intent and enforces the agent loop for build/add/fix/change requests.

dna workbench install      # refresh prompts + stem packs (also runs automatically)
dna workbench uninstall    # opt out — sets aiWorkbench.enabled=false
dna update                 # download latest prompt stems from dna.humaan.app + pack updates
dna update --skip-workbench

Prompt stem packs (.DNA/stems/<id>/)

Each stem includes: prompt.md, guidelines.md, expectations.md, context.md, examples.md.

Category	Examples
Session	/health-check, /dna-update, /work-with-dna
Analysis	/analyze-project, /what-next, /scan-project, /stack-hosting
Features	/ship-feature, /plan-rbac, /generate-feature, /platform-codegen
Agent loop	/agent-loop, /product-analyst, /solution-architect, /backend-engineer, …
Quality	/quality-gate, /pre-push-review
IVF	/ivf-shared-library, /ivf-execute, /plan-ivf
Docs	/sync-impressions, /drift-pr
Memory	/memory-sync, /memory-import, /memory-export
Debug	/dashboard-monitor, /runtime-investigate

Refresh: npx dna update downloads the latest catalog from https://dna.humaan.app/intelligence/api/v1/catalog (offline: bundled fallback).

dna stems list
dna stems show what-next-after-analyze

Slash prompts (type / in chat)

Workbench installs slash commands for every stem that has one — e.g. /work-with-dna, /ship-feature, /analyze-project, /agent-loop, /solution-architect.

Files: .cursor/rules/dna-workbench.mdc, .cursor/skills/dna-workbench/, .cursor/skills/dna-cli/, .cursor/commands/*.md, .DNA/stems/ (and .claude/ mirror).

/dna-* commands install alongside stem slashes — both refresh on dna workbench install, dna init, dna doctor, and dna update.

github

GitHub is connected during dna init via browser login — no GITHUB_TOKEN setup required.

github login

Re-authenticate if push fails.

dna github login

Opens GitHub in your browser (via GitHub CLI or device flow). Token stored in ~/.config/dna/github-credentials.json — never in the repo.

github push

Commit and push the current feature branch (used by feature factory close-out).

dna github push --message "feat: add billing"
dna github push --branch feature/billing --create-branch

github connect

Manual repo override (usually auto-detected from git remote during init).

dna github connect --owner ORG --repo REPO

github issue

Create an issue from classified JSON.

dna github issue --file .DNA/runtime/issues.jsonl

feedback

Report DNA-platform failures upstream to superhumaan/DNA. User app bugs stay in your project's repo. Enabled by default with autoReport: "dna-only".

Configure in .DNA/config.dna.json:

{
  "feedback": {
    "enabled": true,
    "upstream": true,
    "autoReport": "dna-only",
    "includeSuggestedFix": true
  }
}

autoReport	Behaviour
off	Never send upstream
dna-only	DNA stack / CLI / .DNA/ failures only (default)
all	All classified runtime issues upstream

feedback report

dna feedback report --message "doctor failed" --command "dna doctor"
dna feedback report --file error.json --dry-run

feedback sync

Flush the offline queue when the feedback API was unreachable.

dna feedback sync

feedback status

dna feedback status

feedback ingest

Maintainer only — create a deduped GitHub issue from a payload JSON file.

DNA_FEEDBACK_TOKEN=ghp_... dna feedback ingest --file payload.json
DNA_FEEDBACK_TOKEN=ghp_... node scripts/feedback-ingest.mjs payload.json

Offline queue: .DNA/data/feedback-queue.jsonl (gitignored). Install fingerprint: anonymous UUID in ~/.config/dna/install-id.

See Integrations — Upstream feedback.

ai

ai connect

dna ai connect --provider mock
dna ai connect --provider openai --model gpt-4o
dna ai connect --provider anthropic --model claude-sonnet-4-20250514

ai repair

Run repair workflow from a classified issue file.

dna ai repair --file issue.json
dna ai repair --file issue.json --dry-run

Never auto-merges. Always requires human review.

ai force-repair

Re-run repair for open Aggressive Repair Loop blockers (from CellularMemory / runtime fingerprints).

dna ai force-repair
dna ai force-repair --dry-run

Requires ai.repair.aggressive (default on). See Lab and repair v0.6.3 and Lab + runtime v0.6.4.

Benign disconnects (write EPIPE, ECONNRESET) are not captured or repaired — see v0.6.4 noise filter.

stack

Approved system shapes — prevents incoherent technology mixes (e.g. Next.js + Vite, Ghost + React).

stack list

dna stack list

stack recommend

dna stack recommend --description "B2B SaaS dashboard"

stack show

dna stack show

Shows configured archetype, detected dependencies, and conflicts.

marketplace

marketplace list

dna marketplace list
dna marketplace list --channel stable

marketplace search

dna marketplace search --query vite
dna marketplace search --category compliance

Categories: languages, frameworks, platforms, disciplines, compliance

marketplace install

dna marketplace install frameworks/nextjs
dna marketplace install compliance/gdpr
dna marketplace install combo/nextjs-fullstack
dna marketplace install combo/gdpr-eu-ready

Installs files into .DNA/knowledge/ and records version in config.

Purpose bundles (combo/*): installs required + preferred knowledge packs, then injects linked prompt stem packs (.DNA/stems/), slash commands, always-on Cursor bundle rules, and refreshes AI workbench context. Browse: dna.humaan.app/marketplace#bundles. Catalog exposes bundles[] on /marketplace/api/v1/catalog.

plan rbac

Generate a full RBAC + zero trust implementation plan from plain language.

dna plan rbac \
  --quote "No employee unless I grant access. Roles: manager, hr, operations, admin" \
  --feature dashboard

dna plan rbac --roles manager,hr,operations,admin --feature dashboard
dna context rbac

Writes .DNA/plans/rbac-*.md, permission matrix, and installs security/rbac-zero-trust knowledge pack.

platform

Browse and plan features DNA learned from production reference projects (a production app, a production app, ops tooling, a production app).

dna platform list
dna platform projects
dna platform project humaan

See platform.md.

plan feature

Generate an end-to-end implementation plan for a platform feature.

dna plan feature admin-portal --quote "Admin portal with Google directory sync"
dna plan feature azure-deploy --reference-project app
dna context platform
dna context platform --feature admin-portal

Installs platforms/dna-stack knowledge pack. See platform.md.

plan compliance

Generate tiered compliance controls for GDPR, HIPAA, ISO 27001, SOC 2, or PCI.

dna compliance list
dna plan compliance --frameworks gdpr,iso27001 --tier sme --quote "EU B2B SaaS"
dna plan compliance --framework hipaa --tier corporate
dna context compliance --tier sme --frameworks gdpr,hipaa

Writes .DNA/plans/compliance-*.md and control matrix. See compliance.md.

analyze

Deep analysis of an existing project: structure, auth, integrations, vertical gaps.

dna analyze --deep
dna analyze --verticals behaviour,runtime,rbac

document

Reverse-engineer Impressions and system map from codebase.

dna document --from-code
dna document --from-code --force

plan ivf

Generate an Integrating Vertical Functions plan for brownfield projects.

dna plan ivf --quote "B2B SaaS — RBAC, GDPR, runtime"
dna plan ivf --verticals behaviour,runtime,rbac,compliance,sharedLibrary,impressions
dna plan ivf --gaps-only
dna context ivf

See ivf.md.

Environment variables

Variable	Purpose
GITHUB_TOKEN	GitHub API access
OPENAI_API_KEY	OpenAI repair provider
ANTHROPIC_API_KEY	Anthropic repair provider
DNA_PROJECT_ID	Runtime project identifier
DNA_MARKETPLACE_URL	Override marketplace base URL
DNA_REFERENCE_ROOT	Parent directory for platform reference repos
DNA_GDPR_SOURCE_DOCS	Source path for GDPR doc ingest (contributors)
GIT_SHA	Runtime release tag

Full notes: integrations.md.