Nexlem SDK Query Reference

Hand-written reference for all nexlem-sdk query handlers. These handlers are the machine-readable boundary between Claude Code skills and the framework binary.

Invocation: nexlem-sdk query <namespace> [--flags]

Each handler returns JSON to stdout. The dispatcher uses three exit codes:

Code	Meaning
0	success — handler ran and wrote JSON to stdout
1 = user error	bad or missing namespace (including a flag-leading value), unknown namespace, --pick with no value or a flag-leading value, or --pick field not present in the result
2 = internal error	unhandled exception inside the handler

Handler-level vs dispatcher-level: Each handler always exits 0 internally — handler errors (e.g. project not initialized, invalid wizard payload) are returned as structured JSON with "ok": false and exit 0. However, the dispatcher can exit 1 before the handler runs when the invocation is malformed (unknown/missing namespace or bad --pick flag), and exit 2 if the handler throws an unhandled exception. The per-handler "Exit codes" lines below describe handler-internal behavior only; this table governs the full exit-code contract.

See docs/STABILITY.md for tier definitions (stable vs evolving).

Handlers

version

Tier: stable (since v2.2.0)

Purpose: Returns the framework version sourced from scaffold/manifest.json. Use this to verify which framework version is installed in a consumer project, or to assert the correct version in CI.

Synopsis: nexlem-sdk query version

Flags: none

Example:

node_modules/.bin/nexlem-sdk query version

Output shape:

{ "version": "2.2.0" }

Exit codes: 0 (always — handler-internal; see dispatcher exit-code table above for full contract)

state.healthy

Tier: stable (since v2.2.0)

Purpose: Returns a structured health report for an initialized Nexlem project. Checks that .nexlem/ exists, the SQLite database is readable and passes PRAGMA integrity_check, and the merged config parses without errors. Use this after a restore, migration, or DB reinit to confirm the project state is coherent.

Synopsis: nexlem-sdk query state.healthy

Flags: none (must be run from an initialized project directory)

Example:

cd my-content-site
node_modules/.bin/nexlem-sdk query state.healthy

Output shape:

{
  "ok": true,
  "checks": [
    { "name": "nexlem_dir",     "status": "pass" },
    { "name": "db_readable",    "status": "pass" },
    { "name": "db_integrity",   "status": "pass" },
    { "name": "config_valid",   "status": "pass" }
  ]
}

Project not initialized response:

{ "ok": false, "reason": "project_not_initialized", "checks": [] }

Exit codes: 0 (always — handler-internal; project-not-initialized errors are returned as structured JSON; see dispatcher exit-code table above for full contract)

setup.check

Tier: stable (since v2.2.0)

Purpose: Returns a structured report on project initialization, configuration, hook installation, and framework manifest presence. Use this in CI to verify the install and scaffold steps completed correctly. Lighter than state.healthy — does not open the SQLite database; checks filesystem presence and config parse only.

Synopsis: nexlem-sdk query setup.check

Flags: none (must be run from an initialized project directory)

Example:

cd my-content-site
node_modules/.bin/nexlem-sdk query setup.check

Output shape:

{
  "ok": true,
  "checks": [
    { "name": "nexlem_exists",    "status": "pass" },
    { "name": "config_valid",     "status": "pass" },
    { "name": "hooks_installed",  "status": "pass" },
    { "name": "manifest_present", "status": "pass" }
  ]
}

Checks evaluated:

Project not initialized response:

{ "ok": false, "reason": "project_not_initialized", "checks": [] }

Exit codes: 0 (always — handler-internal; see dispatcher exit-code table above for full contract)

skill.inventory

Tier: evolving (since v2.2.0)

Purpose: Returns a structured inventory of all skills and agents registered in scaffold/manifest.json. Use this to programmatically enumerate available commands or to verify that a setup step copied the expected assets.

Evolving: the description field is not yet in the manifest schema and is absent from each entry. The shape of entries may gain fields in future releases.

Synopsis: nexlem-sdk query skill.inventory

Flags: none

Example:

node_modules/.bin/nexlem-sdk query skill.inventory

Output shape:

{
  "framework_version": "2.2.0",
  "skills": [
    { "name": "init.md", "path": ".claude/skills/nexlem/init.md", "required": true }
  ],
  "agents": [
    { "name": "nexlem-research.md", "path": ".claude/agents/nexlem-research.md", "required": true }
  ]
}

Exit codes: 0 (always — handler-internal; see dispatcher exit-code table above for full contract)

wizard.validate

Tier: evolving (since v2.2.0)

Purpose: Validates a full wizard answer payload (structural + cascade) at the skill-to-SDK boundary. Used by init.md and reconfigure.md before any file write. Accepts the payload as a JSON string via --payload.

Evolving: validation rules change as the wizard wizard gains new sections or sections are renamed. Do not depend on specific issues[].path strings across releases.

Synopsis: nexlem-sdk query wizard.validate --payload <json-string>

Flags:

Example:

node_modules/.bin/nexlem-sdk query wizard.validate \
  --payload '{"projectDir":"/path/to/project","sections":[...]}'

Output shape — valid payload:

{ "ok": true }

Output shape — invalid payload:

{
  "ok": false,
  "section": "business",
  "issues": [
    { "path": "answers.voice", "message": "Required" }
  ]
}

Exit codes: 0 (always — handler-internal; validation errors are returned in the JSON body; see dispatcher exit-code table above for full contract)

Common Patterns

Check before acting (shell scripts)

SETUP_OUT="$(node_modules/.bin/nexlem-sdk query setup.check 2>/dev/null)"
OK="$(echo "$SETUP_OUT" | node -e "const d=JSON.parse(require('node:fs').readFileSync('/dev/stdin','utf8')); process.stdout.write(String(d.ok));")"
if [ "$OK" != "true" ]; then
  echo "Project is not ready — run /nexlem init first" >&2
  exit 1
fi

Pipe to jq for readable output

node_modules/.bin/nexlem-sdk query state.healthy | jq '.checks[] | select(.status != "pass")'

Extract single field

node_modules/.bin/nexlem-sdk query version | node -e \
  "const d=JSON.parse(require('node:fs').readFileSync('/dev/stdin','utf8')); console.log(d.version);"

Edit this page on GitHub