@benkei-ai/cli

The benkei command-line tool. Inspect agent templates, walk processes step-by-step, browse memory sections (namespaces), run eval suites, verify event chains, and serve the implementation dashboard (browser UI) from any catalog repo.

Install

Local devDep (recommended — one entry in your repo, pnpm viz script):

pnpm add -D @benkei-ai/cli

Or invoke ad-hoc without installing:

bunx @benkei-ai/cli admin --template ./dist/index.js --open

Quick start — visualise a catalog

From inside any @benkei-ai/* / @cryptobenkei/* / @benkei-templates/* package (e.g. @benkei-ai/templates, @cryptobenkei/hulahoop, your own catalog):

pnpm build                                          # produce dist/index.js
bunx @benkei-ai/cli admin --template ./dist/index.js --open

The dashboard opens in your browser with three things to explore:

• Agent tree — the manager + every child blueprint (managers, leaves) in declaration order, with role badges, default-child marker, and lifecycle state list.
• Processes — every process the catalog ships, rendered step-by-step: node type (human / llm / action / branch / flow / collect_documents), step prompt, the JSON slice it fills (produces.path + schema tree), outgoing transitions and their conditions.
• Memory — declared namespaces per agent (= the wiki/section layout the agent will own), with introspected Zod schemas.

Plus, per agent: full prompt + per-lifecycle-state instructions, the resolved capability requirements (joined with the @benkei-ai/core capability catalog: scope, side effects, cost class, error codes, identity bindings), and the Zod I/O contracts for each capability.

Multiple catalogs at once

Pass --template multiple times (or point at a workspace directory that contains several catalog packages — every @benkei-ai/* / @cryptobenkei/* / @benkei-templates/* package under it is discovered):

bunx @benkei-ai/cli admin \
  --template ./catalogs/standard/dist/index.js \
  --template ./catalogs/private/dist/index.js \
  --open

Flags

| Flag | Default | Purpose | |------|---------|---------| | --template <path> | (required, repeatable) | Built catalog file (dist/index.js) or a workspace/package directory | | --port <n> | random free port | HTTP port | | --host <h> | 127.0.0.1 | Bind interface | | --open | off | Open the dashboard in your default browser |

What does discovery look for?

A package is treated as a catalog when its package.json name matches one of:

• @benkei-templates/* (legacy)
• @benkei-ai/*
• @cryptobenkei/*
• or its package.json has "benkeiCatalog": true (opt-in for any other scope)

Inside each candidate, every export with the shape of a BlueprintContract ({ manager, childTemplates }) is loaded, deduped by manager identity. ProcessTemplates (anything with slug + nodes[] + edges[]) are collected from the same modules and resolved against blueprint references.

Other commands

benkei logs <agentDir>                   # summarise an agent's event log
benkei verify <agentDir>                 # verify the signed event chain
benkei dashboard <rootDir> <rootDid>     # tenant-wide activity dashboard
benkei export <agentDir> <bundleDir>     # write a portable agent bundle
benkei import <bundleDir> <agentDir> <did>
benkei eval <suite.yaml> [--run --template <path>]

All commands operate against on-disk agent state (no network). The verify, logs, dashboard, export, import paths use SQLite via better-sqlite3, which is loaded lazily — you only need to install it if you run those commands:

pnpm add -D better-sqlite3

The admin (dashboard) command never opens a real agent store, so better-sqlite3 is not required for catalog visualisation.

Links

• Foundation: @benkei-ai/core
• Standard catalog: @benkei-ai/templates
• Source: github.com/benkei-ai/benkei-agent-core/tree/main/packages/cli

License

ISC