flashsh CLI

The flashsh command is FLASH's sovereign zero-knowledge shell — optimized for private RAG, agent memory, and integrity proofs.

Keep the key — do not weaken the default

flashsh wrap-key seals the master; FLASH never holds it. Default flash-zk is strong. You can weaken it by leaking .flash-wrap or turning protection off. No independent audit in this release. Mission · Trust Model.

---

Installation

npm install -g flash-zk

Or via npx:

npx flashsh init

---

Key format (this release only)

FLASH 1.3.x recognizes one sealed-key format. Do not invent alternate file layouts — FlashClient will reject them.

Artifact	Format	Example / rule
Wrap key (.flash-wrap)	One line: flash_wrap_ + 43-char base64url	flash_wrap_xK9… — generated by flashsh wrap-key only
Master secret (inside .flash-take)	flash_master_ + base64url when CLI generates it	Or your own passphrase if you passed --key (16+ bytes, not weak)
Sealed blob (.flash-take)	Line 1: FLASHTAKE1 · Line 2: AES-256-GCM payload (base64)	Magic FLASHTAKE1 only — no v2 / custom headers yet

Encryption inside .flash-take: FlashCipher with wrap key, salt flash-key-wrap-v1, AAD flash-take:secretKey.

If you hand-edit keys or use a home-grown “encrypted key file”, FLASH will not load it unless it matches the table above.

---

How wrap-key works (step by step)

flashsh wrap-key              # in your app project directory
# or
flashsh wrap-key --dir ./config --force

1. Wrap key — CLI generates a random flash_wrap_… string and writes one line to .flash-wrap (mode 0600 where supported).
2. Master secret — CLI generates flash_master_… or seals the value you passed with --key (never printed).
3. Seal — Master is encrypted with the wrap key → .flash-take (FLASHTAKE1 + ciphertext).
4. Done — CLI prints paths only. No secrets on stdout.

At runtime, FlashClient (or flashsh init / ask / …) with no --key:

1. Looks for .flash-take in --dir / cwd (wrapKeyDir).
2. Loads wrap key from .flash-wrap or FLASH_WRAP_KEY.
3. Unseals → uses result as secretKey for encryption.

  flash_wrap_…  (.flash-wrap)     ──┐
                                    ├──► unseal ──► flash_master_… (secretKey)
  FLASHTAKE1 + ciphertext (.flash-take) ──┘

Your responsibilities:

• Add .flash-wrap to your repo’s .gitignore (FLASH does not gitignore it for you).
• Back up the wrap key securely — lost wrap key = sealed master unrecoverable.
• Treat FLASH_WRAP_KEY in CI like a production secret.
• Committing .flash-take without the wrap key is intentional; leaking both together removes the benefit.

---

Commands

Wrap master key (recommended)

flashsh wrap-key
flashsh wrap-key --key "your_long_master_passphrase_here"

File	Purpose	Commit?
.flash-wrap	Random wrap key (decrypts the take file)	No — add to your app’s .gitignore or use FLASH_WRAP_KEY in CI
.flash-take	Sealed master secretKey (FLASHTAKE1)	Yes — safe without .flash-wrap

import { FlashClient } from "flash-zk";

const client = new FlashClient({
  storagePath: "./flash_data",
  wrapKeyDir: "./config", // optional; default cwd
});

Initialize workspace

flashsh init

Creates ./flash_data, writes a welcome sample, and ingests it into Private RAG (cli_knowledge). Uses .flash-take + .flash-wrap when present; otherwise requires --key or a default dev key is not used in production setups.

Interactive REPL

flashsh
# flashsh> client.privateRAG('kb').ask('question')

Ingest knowledge (Private RAG)

flashsh ingest ./notes.txt
echo "FLASH encrypts client-side" | flashsh ingest -

Semantic search (not a chatbot)

flashsh ask "does the server see plaintext?"

ask searches ingested documents via semantic similarity. It returns the closest matching chunks — not a conversational LLM reply.

Integrity proof

flashsh proof users

---

Options

Flag	Description
--storage ./data	Storage directory (default: ./flash_data)
--key secret	Master secret key (or input to wrap-key)
--dir .	Directory for .flash-wrap / .flash-take
--force / -f	Overwrite existing wrap/take files
--uri flash://host:6742	Remote FLASH server
--quiet / -q	Suppress metadata output

---

Recommended workflow

# 1. Keys (once per environment)
flashsh wrap-key --dir .
echo ".flash-wrap" >> .gitignore   # in YOUR project

# 2. Bootstrap data
flashsh init

# 3. Add documents
flashsh ingest medical-notes.txt

# 4. Search
flashsh ask "side effects"

Collection used: cli_knowledge under {storagePath}/flash_db/.

---

Related

• Trust Model & Audit Roadmap
• Positioning & Identity
• Intelligence Console
• Private RAG