CLI reference

kscope is the command. It creates a vault, wires your editor to it, and answers questions about both.

npm install -g @kleos-research/kaleidoscope
kscope --help

The full help text is the authority on every argument.

The verbs

To do this	Run	Page
Create a vault and wire your editor	init	Connect an editor
Write the instruction file and skill	init	Agent instructions
Name a vault so an editor can start with it	init-profile, profile create, profile import	Profiles and vaults
See, inspect or forget a profile	profile list, profile show, profile launch, profile remove	Profiles and vaults
Find out which vault you are talking to	where	Diagnostics
Check the key, the model, the vault	gate, activate, model, vault-verify	Diagnostics
Run an engine for an agent	mcp, call	MCP reference
Migrate, preview or delete a vault	vault-migrate, vault-preview, vault-delete	Operations
Upgrade a vault, or undo the upgrade	vault-upgrade, vault-rollback	Operations
Read the tool contract	schema	MCP reference
Read the third-party notices	licences	—

kscope init appears twice because one run does both jobs: it creates the vault, then tells every agent on this machine that the vault exists.

The flags

Flag	On	Effect
--profile NAME	mcp, call	Work in the vault that profile names. Nothing else accepts it.
--no-wire	init	Create the vault and write no editor configuration.
--shared	init	Wire this project’s agents to the shared vault in your home folder instead of giving the project its own.
--vault PROFILE	init	Wire this project’s agents to the vault an existing profile names, and create none.
--confirm HEAD	vault-rollback	Undo the upgrade. Take the exact command the dry run prints.
--root-only	where	Print only the vault root and the project it came from.
--cross-backend	vault-verify	Widen the check.
--help, -h	any invocation	Print the command surface.
--version, -V	any invocation	Print the version.

kscope init takes no --profile. It works on the directory you are in, or on a root you name as a positional argument.

There is no --engine, no --dry-run and no --yes. An unknown verb prints the help text; an unknown argument to init is refused by name, and nothing is created.

Where the wiring goes

What	Where	Why
MCP server entry	the project, or for Claude Code, that project’s entry in ~/.claude.json	Each project’s agents open that project’s own vault. init writes the entry in every existing checkout of the repository, and kscope where says when a newer worktree needs one.
Instruction file and skill	the project	Git carries them into a worktree or clone.

What init writes, and what it leaves alone

• Kaleidoscope writes only the block it owns, between ownership comments wherever the file format has room for them.
• Every file it writes gets a receipt beside it: config.toml.kaleidoscope-owner.json beside a host configuration, CLAUDE.md.kaleidoscope-instruction-owner.json beside an instruction file. Claude Code’s receipt for a project’s entry sits beside ~/.claude.json, one per project.
• A file it changes rather than creates is copied to <name>.kaleidoscope-backup first. The rest of the file is untouched.
• If what it finds no longer matches the receipt, it stops at that file and reports that step as failed. The other steps still run.
• The configuration it writes carries no token, no provider key and no vault location. It names this executable, a profile, and the tools search and remember.
• Running kscope init again is safe. An existing vault is left as it is and the wiring is re-checked.

The second executable

Some verbs written about elsewhere — connect, disconnect, config, doctor, teardown, profile use, instructions install, and the whole account surface — belong to kaleidoscope, a second executable built from source and published on no channel. Nothing on this site asks you to run one. Account commands lists them.