Official command-line interface (@aikdna/kdna-cli@0.43.5) for authoring, password-protecting, validating, reading, and comparing .kdna judgment works.
Public, local, and password-protected .kdna workflows in @aikdna/kdna-cli@0.43.5 run offline on Node.js >=22 and permanently require no online account.
- Website & KDNA Reader (macOS): aikdna.com · Download KDNA Reader & KDNA Whitepaper v1.0.1
- Specifications & Release Matrix:
aikdna/kdna(release-coordinates.json) - Agent Skills & MCP:
aikdna/kdna-skills(kdna-creator&kdna-loader) - Public Reference Works:
aikdna/kdna-assets
Four everyday workflows with a .kdna judgment work—every command below runs directly:
# 1. Create: generate a ready-to-compile starter draft (omit --example for a TODO template)
kdna init --example --mode interview --output draft.json
kdna validate-input draft.json --format human
kdna create --draft draft.json --output my-judgments.kdna --allow-create
# 2. Read only what the task needs: browse the catalog first, then read selected judgments with full context
kdna read my-judgments.kdna --mode catalog --allow-read --format human
kdna read my-judgments.kdna --mode exact_selection --judgment-id decision:first-dilemma --allow-read --compact
# 3. Protect with a local password (offline AEAD encryption; no account, no network)
printf '%s' 'a long passphrase' > password.txt
kdna protect my-judgments.kdna --output locked.kdna --password-file password.txt
kdna read locked.kdna --mode exact_selection --judgment-id decision:first-dilemma --allow-read --password-file password.txt --format human
# 4. Compare two versions in plain text
kdna init --example --mode works --output revised-draft.json
kdna create --draft revised-draft.json --output revised.kdna --allow-create
kdna diff my-judgments.kdna revised.kdna --format humanPrefer conversational co-creation with an AI agent instead of editing JSON directly? Install aikdna/kdna-skills (kdna-creator for guided interviews, distillation from existing works, or research; kdna-loader for task-scoped selective reading). To explore a complete 45-judgment reference work, open KDNA Whitepaper (v1.0.1, native zh-CN & en, by Zhang Ling / 张零, CC BY 4.0) in KDNA Reader for macOS or inspect it directly from aikdna/kdna-assets.
Passwords are read only from --password-file or an inherited descriptor (--password-fd, >=3)—never from command-line arguments. Reading and writing require explicit flags so agent hosts never access or overwrite files silently:
| Operation | Command | Explicit Permission |
|---|---|---|
| Scaffold, compile, and check authoring input | init, compile, validate-input |
None (reads/prints input or writes a new JSON draft) |
Pack a native 0.6.0 .kdna work |
create |
--allow-create (atomic no-replace save) |
| Encrypt payload locally with a password | protect |
--password-file or --password-fd |
| Inspect metadata and validate integrity | inspect, validate |
Explicit file path (plus password source if protected) |
| Read catalog, selected judgments, or expansions | read |
--allow-read (plus password source if protected) |
Compare two .kdna versions |
diff |
Explicit file paths (plus password source if protected) |
| Export or repack full authored source | source-open, source-pack |
--allow-source and exact --expected-a SHA-256 |
Migrate an explicit 0.5.0 public source to 0.6.0 |
convert |
--allow-source and exact --expected-a SHA-256 |
# Authoring & compilation
kdna init --output draft.json
kdna init --mode interview --output interview-draft.json
kdna validate-input draft.json --format human
kdna create --draft draft.json --output asset.kdna --allow-create
kdna compile draft.json --output authored.json
kdna create authored.json --output asset.kdna --allow-create
# Local password protection & inspection
kdna protect asset.kdna --output protected.kdna --password-file ./password.txt
kdna inspect asset.kdna
kdna inspect protected.kdna --password-fd 3 3< ./password.txt
kdna validate asset.kdna
# Scoped reading & multi-judgment selection
kdna read asset.kdna --mode catalog --budget 1000000 --allow-read
kdna read asset.kdna --mode exact_selection --judgment-id j:one --judgment-id j:two --allow-read --compact
kdna read asset.kdna --mode exact_selection --judgment-id j:one,j:two --allow-read --format human
kdna read asset.kdna --session --allow-read
# Version comparison, source revision & 0.5 -> 0.6 migration
kdna diff old.kdna new.kdna --format human
kdna source-open asset.kdna --expected-a 'sha256:<64-lowercase-hex-digits>' --allow-source
kdna source-pack asset.kdna --edits edits.json --expected-a 'sha256:<64-lowercase-hex-digits>' --output revised.kdna --allow-source
kdna convert asset.kdna --expected-a 'sha256:<64-lowercase-hex-digits>' --output converted.kdna --allow-source- Authoring drafts (
init,validate-input,compile):initgenerates akdna.draft/1document across four modes (minimal,interview,works,research) in English (--lang en, default) or Chinese (--lang zh). Pass--examplefor an immediately compilable starter, or omit it forTODO:prompts checked beforecompileandcreate --draft.validate-inputchecks drafts, full authored JSON, andsource-open.editsdocuments. Seedocs/authoring-field-reference.md. - Selective reading (
read):cataloglists judgment IDs without bodies;exact_selectionreturns the chosen judgments together with their mandatory supporting and qualifying context (--judgment-idmay repeat or take a comma-separated list;--compacttrims wrapper envelopes while keeping every safety boundary, reason, example, and relation intact;--budgetdefaults to1000000bytes oncatalog/exact_selectionand4000000bytes onwhole_asset).--format humanrendersinspect,validate,read, anddiffin clean plain text (using English method-role labels on English works and Chinese labels on Chinese works). Seedocs/consumption-runtime.md. - Local password protection (
protect): Encryptspayload.kdnabwith an offline authenticated-encryption envelope (PBKDF2+AES-256-GCM), stripping one trailing newline from the supplied password file/descriptor and zeroing secret buffers on exit. Wrong passwords fail withPROTECTION_AUTHENTICATION_FAILED; missing passwords fail withKDNA_PASSWORD_REQUIRED. Keep your unencrypted public.kdnaor authoring draft for future revisions (source-openaccepts public containers only). - Safe saving & exit codes: File saves never overwrite existing paths or symlinks—always choose a new filename for a revision. Exit codes:
0on success/ready,1on validation/auth/save rejection, and2on invalid CLI arguments or retired commands.
const { run } = require('@aikdna/kdna-cli');
const exitCode = await run(['validate', '/absolute/path/asset.kdna'], process.stdout);run(argv, stdout = process.stdout, stdin = process.stdin) is the package's sole programmatic export:
- Resolves to the numeric CLI exit code (
0,1, or2) after sequential writes complete, honoring Node.jsWritablebackpressure. - Accepts any async iterable of UTF-8 lines/chunks on
stdinfor--sessionJSONL mode, closing cleanly on EOF or output error without leaving background handles open.
@aikdna/kdna-cli@0.43.5 binds to exact companion packages (@aikdna/kdna-core@0.37.9 and @aikdna/kdna-read@0.13.3, container 0.6.0, recorded in public-contract-binding.json). See docs/native-delivery.md and examples/team-update/README.md for offline host setup:
npm ci --prefix release-surface/native-offline-host --offline --ignore-scripts --omit=optional --no-audit --no-fund
export NODE_PATH="$PWD/release-surface/native-offline-host/node_modules"
npm run build
npm testBoundaries: Technical validation confirms container structure and digests, never whether a judgment is true or suitable for your task. Reading content (--allow-read) delivers structured judgment text and never grants filesystem mutation, network, payment, or external execution permissions (see docs/asset-authorization.md).
Code is licensed under Apache-2.0; documentation and bundled examples are licensed under CC BY 4.0 as stated in NOTICE.