@aikdna/kdna-cli

The official command-line runtime for KDNA Core v1 judgment assets.

KDNA CLI inspects, validates, packs, unpacks, and loads .kdna files. It is the consumer/runtime side of the official KDNA toolchain. Formal authoring is handled by KDNA Studio CLI and Studio Core.

KDNA Core v1 does not require a public registry, marketplace, quality badge, or signature system. The current first-run path uses local .kdna files.

Authorization and runtime-load decisions are defined in aikdna/kdna, not in this repository. kdna plan-load is the CLI diagnostic surface for that contract and MUST call the LoadPlan API from @aikdna/kdna-core instead of deriving authorization state directly from manifest fields.

Install

npm install -g @aikdna/kdna-cli

5-Minute Path

kdna demo minimal ./minimal
kdna inspect ./minimal
kdna validate ./minimal
kdna plan-load ./minimal --json
kdna pack ./minimal ./minimal.kdna
kdna validate ./minimal.kdna --runtime
kdna plan-load ./minimal.kdna --json
kdna load ./minimal.kdna --profile=compact --as=prompt

Successful validation returns:

{
  "format_valid": true,
  "schema_valid": true,
  "payload_valid": true,
  "checksums_valid": true,
  "load_contract_valid": true,
  "overall_valid": true,
  "problems": []
}

Core Commands

| Command | Purpose | |---|---| | kdna demo minimal <dir> | Create a minimal v1 source directory | | kdna inspect <path> | Inspect a v1 source dir or .kdna container | | kdna validate <path> | Validate format, schema, payload, checksums, and load contract | | kdna plan-load <path> --json | Return the Core LoadPlan before runtime load | | kdna plan-load <path> --json --has-password | Diagnose password-authorized load state | | kdna plan-load <path> --json --entitlement-status active | Diagnose receipt/entitlement load state | | kdna pack <source-dir> <output.kdna> | Pack a v1 source directory | | kdna unpack <input.kdna> <output-dir> | Unpack a v1 container | | kdna load <path> --profile=<index|compact|scenario|full> --as=<json|prompt> | Render judgment context for agents or tools | | kdna setup | Install the kdna-loader skill for supported agents | | kdna doctor --agents | Check agent loader installation |

Producer Path

Use Studio CLI to create formal v1 .kdna assets:

npm install -g @aikdna/kdna-studio-cli
kdna-studio create my_domain --name @yourscope/my_domain
kdna-studio card add my_domain axiom \
  --field one_sentence="Prefer specific evidence over broad claims" \
  --field full_statement="When reviewing content, prefer specific evidence over broad claims because unsupported generalizations make the judgment impossible to verify or improve." \
  --field why="Broad claims hide the actual reason for a judgment, so reviewers cannot tell whether the conclusion is evidence based, reusable, or merely plausible sounding." \
  --field applies_when='["reviewing content"]' \
  --field does_not_apply_when='["pure formatting"]' \
  --field failure_risk="generic advice"
kdna-studio card approve my_domain --all --by expert --statement "I confirm this judgment."
kdna-studio export my_domain --format v1 --out ./my_domain.kdna
kdna validate ./my_domain.kdna --runtime
kdna plan-load ./my_domain.kdna --json
kdna load ./my_domain.kdna --profile=compact --as=prompt

Legacy Compatibility

Older CLI commands for registry install, compare, trace, licensing, identity, or pre-v1 dev source workflows may still exist for backward compatibility. They are not the KDNA Core v1 launch path.

New integrations should use the v1 Core route:

source or Studio project
→ v1 .kdna container
→ kdna validate
→ kdna plan-load
→ kdna load
→ agent/runtime context

Runtime Authorization Contract

The source of truth is aikdna/kdna:

• specs/kdna-authorization-contract.md
• schema/load-plan.schema.json
• conformance/authorization/cases.json
• conformance/authorization/goldens/*.loadplan.json

This CLI is a diagnostic control plane. It may display, validate, and transport LoadPlan results, but it must not define access modes, entitlement profiles, issue codes, crypto profiles, or fail-closed policy independently.

Current local authorization path:

kdna validate ./asset.kdna --json
kdna plan-load ./asset.kdna --json
kdna plan-load ./asset.kdna --json --has-password
kdna plan-load ./asset.kdna --json --entitlement-status active
kdna load ./asset.kdna --profile=compact --as=prompt

plan-load requires a version of @aikdna/kdna-core that exports the LoadPlan v1 API. Until that dependency is released and installed, the command fails with a version-gate error instead of falling back to duplicated CLI-side parsing.

Development

git clone https://github.com/aikdna/kdna-cli.git
cd kdna-cli
npm install
npm test

Related

• KDNA Core
• KDNA Studio CLI
• KDNA Skills
• aikdna.com

License

Apache-2.0