@aikdna/kdna-cli

@aikdna/kdna-cli

The official command-line runtime for KDNA judgment assets.

KDNA CLI inspects, validates, packs, unpacks, plans, authorizes, and loads .kdna files. Formal authoring belongs to KDNA Studio. The recommended user path starts from one explicit file; neither a global asset library nor a Skill installation is required by the protocol.

Install

npm install -g @aikdna/kdna-cli

File-first quick start

kdna demo judgment ./demo-judgment
kdna pack ./demo-judgment ./demo-judgment.kdna
kdna inspect ./demo-judgment.kdna
kdna validate ./demo-judgment.kdna
kdna plan-load ./demo-judgment.kdna
kdna load ./demo-judgment.kdna --profile=compact --as=json

To approve that exact file for one workspace, save the current task text in a regular file and use the workspace contract:

kdna attach ./demo-judgment.kdna --cwd ./my-project \
  --role article-writing --applies-to draft --does-not-apply-to code --yes
kdna attachments --cwd ./my-project
kdna resolve --cwd ./my-project --task-file ./current-task.txt

attach copies the validated bytes to an immutable digest snapshot under ./my-project/.kdna/. The source file may then move without changing the workspace fact. Omit --yes for an interactive approval prompt; non-interactive callers must provide it explicitly.

| Command | Responsibility | | ------------------------------------- | ------------------------------------------------------------------- | | kdna inspect <file | Read container metadata without adopting its judgment | | kdna validate <file | Check format, schema, payload, integrity, and load contract | | kdna plan-load <file | Return a LoadPlan or explicit-file Host ConsumptionPlan | | kdna load <file | Produce a projection or deliver a Capsule to a registered Host | | kdna pack / kdna unpack | Package or inspect a portable asset | | kdna attach / kdna attachments | Approve or list exact workspace-local attachments | | kdna resolve | Return load, ask, skip, or block without projecting content | | kdna disable / enable | Retain an attachment while controlling eligibility | | kdna switch / rollback / remove | Replace, restore, or remove only the workspace relation |

Successful loading proves technical delivery of a named projection. It does not prove that an Agent followed the judgment or that the result became better. An explicit-file load is one-shot and creates no persistent CLI state by default. Add --audit only when you want a content-neutral local receipt; receipts omit source paths, judgment content, and authorization material.

User and Host contract

A consuming Host must start from:

• a file the user explicitly selected for the current operation; or
• an exact workspace, application, session, or user attachment that the Host

previously recorded as user-approved.

The CLI reference implementation records that approval only in <workspace/.kdna/attachments.json, with immutable snapshots in <workspace/.kdna/assets/. It never falls back to a user-global package directory, scans for unrelated assets, or merges parent and child workspace records. The record and snapshots are ignored by Git by default because they may expose private preferences and asset identity.

Saving, discovery, attachment, authorization, applicability, and loading are separate events. A Host must expose active asset identity, version or digest, scope, and reason, and provide controls to disable it, switch it, or roll it back.