Skip to content
The CubeBook 0.1.0 · alpha

Commands

No. 014

The commands of cube 0.1.0. The tables and the help below are what cube itself prints: cube --help lists the commands, and cube <command> --help prints the help of one. Where the help names the plan of a later release, this page says “a later release”.

Commands

Section titled “Commands”
Command What it does
cube tools List the installed tool binaries
cube adopt Take over an existing KB without changing its content files: write .cube/cube.toml, .cube/cube.lock, the hook shims in .cube/hooks/ and the agent skill in .claude/skills/cube/, and commit them
cube check Run every check: the native checks and the kit’s checks; exit 1 when any finding is an ERROR; –format agent prints the fix brief. Writes nothing but the index cache of an adopted KB
cube doctor Check the environment: git, runtime.python, the hooks, cube.path, safe.directory, the machine-local config.yml in the kit’s machinery folder, the formats and the kit’s tools; exit 3 when an item fails
cube setup Set up the git hooks: write cube.path and the absolute git, gh and python3 paths into the global git config, and merge.ff=false and core.hooksPath=.cube/hooks into the clone
cube hook Run by the installed git hooks: the checks, the ratchet and the trailers
cube ls List every indexed file as the Explorer’s tree knows it: path, kind, app, title, and a spec’s state
cube show Show one file’s preview and facts: title, tl;dr, kind, front matter, and a YAML file’s loaded fields
cube inbox List the agent acts awaiting acknowledgement and the malformed Cube-Act trailers, read-only (acks arrive in a later release)
cube skill Render the agent skill from this cube’s command line, check registry and kit.yml, and install it into the KB
cube pack List, add or remove the layer packs of the KB’s kit; never commits
cube help Print this message or the help of the given subcommand(s)

Exit codes

Section titled “Exit codes”
Code Meaning
0 ok
1 ERROR findings: cube check found one, or a hook refuses the commit
2 a usage or configuration error
3 an environment error: a missing tool, an incompatible kit or engine, or a command that is not built yet

Tools

Section titled “Tools”

Any other name runs a tool binary, cube-<name>, from the folder of this cube; cube tools list shows the installed ones. The kit names cube graph (cube-graph ^0.1), cube index (cube-index ^0.1); cube <tool> --help shows a tool’s own commands.

Not in this release

Section titled “Not in this release”

These names are reserved for commands that later releases bring. In this release, cube <name> refuses with exit 3 and says that the command is not built yet, and cube --help does not list it. No tool program can take one of these names.

Command What it will do
cube init Create a new KB from a kit
cube new Create a node from a kit template
cube set Edit one field of a node
cube transition Move a node to another lifecycle state
cube drift Draft an as-built block
cube accept Accept an as-built block
cube reject Reject an as-built block
cube ship Flip a spec to SHIPPED when its work is merged
cube ack Acknowledge agent acts
cube run Run a kit sequence
cube delete Remove a node after an impact check
cube mv Move files or spec folders and rewrite references
cube status Print the dashboard’s data
cube query Run a kit query
cube branch Manage KB variants
cube diff Show a KB-level diff
cube merge Merge KB variants
cube fork Derive a KB with lineage
cube upstream Sync with the parent KB
cube kit Update the kit machinery
cube session Open, resume or close a session
cube agent Launch an agent
cube app Manage apps and their code folders
cube score Print the harness self-score
cube classify Show the classification of a path
cube prune Prune untracked files past retention
cube log Show the lifecycle log of a node
cube self Update or roll back the engine
cube migrate Run content and format migrations
cube tools update Update installed tools

Help of each command

Section titled “Help of each command”

cube

Section titled “cube”
The Cube. `cube <tool> [args]` runs cube-<tool> from the folder of this cube, never from the current folder or PATH.


Usage: cube [OPTIONS] [COMMAND]


Commands:
  tools   List the installed tool binaries
  adopt   Take over an existing KB without changing its content files: write .cube/cube.toml, .cube/cube.lock, the hook shims in .cube/hooks/ and the agent skill in .claude/skills/cube/, and commit them
  check   Run every check: the native checks and the kit's checks; exit 1 when any finding is an ERROR; --format agent prints the fix brief. Writes nothing but the index cache of an adopted KB
  doctor  Check the environment: git, runtime.python, the hooks, cube.path, safe.directory, the machine-local config.yml in the kit's machinery folder, the formats and the kit's tools; exit 3 when an item fails
  setup   Set up the git hooks: write cube.path and the absolute git, gh and python3 paths into the global git config, and merge.ff=false and core.hooksPath=.cube/hooks into the clone
  hook    Run by the installed git hooks: the checks, the ratchet and the trailers
  ls      List every indexed file as the Explorer's tree knows it: path, kind, app, title, and a spec's state
  show    Show one file's preview and facts: title, tl;dr, kind, front matter, and a YAML file's loaded fields
  inbox   List the agent acts awaiting acknowledgement and the malformed Cube-Act trailers, read-only (acks arrive in a later release)
  skill   Render the agent skill from this cube's command line, check registry and kit.yml, and install it into the KB
  pack    List, add or remove the layer packs of the KB's kit; never commits
  help    Print this message or the help of the given subcommand(s)


Options:
      --kb-root <PATH>  The KB root; else CUBE_KB_ROOT, else the walk up from the working folder
  -h, --help            Print help
  -V, --version         Print version

cube tools

Section titled “cube tools”
List the installed tool binaries


Usage: cube tools <COMMAND>


Commands:
  list  Each tool next to cube and each tool the kit requires: version, range, status, path
  help  Print this message or the help of the given subcommand(s)


Options:
  -h, --help  Print help
cube tools list
Section titled “cube tools list”
Each tool next to cube and each tool the kit requires: version, range, status, path


Usage: cube tools list


Options:
  -h, --help  Print help

cube adopt

Section titled “cube adopt”
Take over an existing KB without changing its content files: write .cube/cube.toml, .cube/cube.lock, the hook shims in .cube/hooks/ and the agent skill in .claude/skills/cube/, and commit them


Usage: cube adopt [OPTIONS]


Options:
      --kb-root <PATH>  The KB root; else CUBE_KB_ROOT, else the walk up from the working folder
  -h, --help            Print help

cube check

Section titled “cube check”
Run every check: the native checks and the kit's checks; exit 1 when any finding is an ERROR; --format agent prints the fix brief. Writes nothing but the index cache of an adopted KB


Usage: cube check [OPTIONS]


Options:
      --kb-root <PATH>   The KB root; else CUBE_KB_ROOT, else the walk up from the working folder
      --format <FORMAT>  text: one line per finding and the counts; json: the cube-findings/v1 document; agent: the fix brief, per ERROR its rule, a real fix, what is not a fix and the act it needs [default: text] [possible values: text, json, agent]
      --json             The same as --format json
  -h, --help             Print help

cube doctor

Section titled “cube doctor”
Check the environment: git, runtime.python, the hooks, cube.path, safe.directory, the machine-local config.yml in the kit's machinery folder, the formats and the kit's tools; exit 3 when an item fails


Usage: cube doctor [OPTIONS]


Options:
      --kb-root <PATH>  The KB root; else CUBE_KB_ROOT, else the walk up from the working folder
      --json            Print the cube-doctor/v1 document instead of text
  -h, --help            Print help

cube setup

Section titled “cube setup”
Set up the git hooks: write cube.path and the absolute git, gh and python3 paths into the global git config, and merge.ff=false and core.hooksPath=.cube/hooks into the clone


Usage: cube setup [OPTIONS] [what]


Arguments:
  [what]  What to set up: hooks (the default); mergiraf arrives in a later release [default: hooks] [possible values: hooks, mergiraf]


Options:
      --kb-root <PATH>  The KB root; else CUBE_KB_ROOT, else the walk up from the working folder
  -h, --help            Print help

cube hook

Section titled “cube hook”
Run by the installed git hooks: the checks, the ratchet and the trailers


Usage: cube hook --kb-root <PATH> <name> [-- [args]...]


Arguments:
  <name>     The git hook [possible values: pre-commit, pre-merge-commit, commit-msg, pre-push]
  [args]...  git's arguments: the message file of commit-msg, the remote and URL of pre-push


Options:
      --kb-root <PATH>  The KB root, the work tree's top level (CUBE_KB_ROOT is never read here)
  -h, --help            Print help

cube ls

Section titled “cube ls”
List every indexed file as the Explorer's tree knows it: path, kind, app, title, and a spec's state


Usage: cube ls [OPTIONS]


Options:
      --kb-root <PATH>  The KB root; else CUBE_KB_ROOT, else the walk up from the working folder
      --json            Print the data as JSON
  -h, --help            Print help

cube show

Section titled “cube show”
Show one file's preview and facts: title, tl;dr, kind, front matter, and a YAML file's loaded fields


Usage: cube show [OPTIONS] <PATH-OR-ID>


Arguments:
  <PATH-OR-ID>  A KB-relative path, or a graph node ID such as sub_spec:app/m01/001-x


Options:
      --kb-root <PATH>  The KB root; else CUBE_KB_ROOT, else the walk up from the working folder
      --json            Print the data as JSON
  -h, --help            Print help

cube inbox

Section titled “cube inbox”
List the agent acts awaiting acknowledgement and the malformed Cube-Act trailers, read-only (acks arrive in a later release)


Usage: cube inbox [OPTIONS]


Options:
      --kb-root <PATH>  The KB root; else CUBE_KB_ROOT, else the walk up from the working folder
      --json            Print the data as JSON
  -h, --help            Print help

cube skill

Section titled “cube skill”
Render the agent skill from this cube's command line, check registry and kit.yml, and install it into the KB


Usage: cube skill <COMMAND>


Commands:
  render  Print the agent skill: SKILL.md and references/{commands,findings,acts,workflows}.md, each after a ==> <path> <== line; or write it with --out or --install
  help    Print this message or the help of the given subcommand(s)


Options:
  -h, --help  Print help
cube skill render
Section titled “cube skill render”
Print the agent skill: SKILL.md and references/{commands,findings,acts,workflows}.md, each after a ==> <path> <== line; or write it with --out or --install


Usage: cube skill render [OPTIONS]


Options:
      --install          Write the skill into the KB's .claude/skills/cube/ (an adopted, writable KB only), where cube check compares it (SKILL_STALE); commit it after
      --out <DIR>        Write the files into DIR instead of printing them
      --target <TARGET>  claude: the Claude Code skill (the default); agents-md, the AGENTS.md section, arrives after the alpha [default: claude] [possible values: claude, agents-md]
      --kb-root <PATH>   The KB root; else CUBE_KB_ROOT, else the walk up from the working folder
  -h, --help             Print help

cube pack

Section titled “cube pack”
List, add or remove the layer packs of the KB's kit; never commits


Usage: cube pack <COMMAND>


Commands:
  list    The packs kit.yml declares: version, purpose, skills and agents
  add     Install a pack from a local folder into the KB and declare it in kit.yml; refuses links, hooks/, unsafe paths and name clashes, and then writes nothing
  remove  Remove a pack's files and its kit.yml entry (a rule change to commit)
  help    Print this message or the help of the given subcommand(s)


Options:
  -h, --help  Print help
cube pack list
Section titled “cube pack list”
The packs kit.yml declares: version, purpose, skills and agents


Usage: cube pack list [OPTIONS]


Options:
      --kb-root <PATH>  The KB root; else CUBE_KB_ROOT, else the walk up from the working folder
  -h, --help            Print help
cube pack add
Section titled “cube pack add”
Install a pack from a local folder into the KB and declare it in kit.yml; refuses links, hooks/, unsafe paths and name clashes, and then writes nothing


Usage: cube pack add [OPTIONS] <dir>


Arguments:
  <dir>  The local folder of the pack


Options:
      --kb-root <PATH>  The KB root; else CUBE_KB_ROOT, else the walk up from the working folder
  -h, --help            Print help
cube pack remove
Section titled “cube pack remove”
Remove a pack's files and its kit.yml entry (a rule change to commit)


Usage: cube pack remove [OPTIONS] <name>


Arguments:
  <name>  The pack's name


Options:
      --kb-root <PATH>  The KB root; else CUBE_KB_ROOT, else the walk up from the working folder
  -h, --help            Print help