metaphor-cli

Orchestrate independent project repos.

Metaphor is a meta-CLI that manages a workspace of standalone project repos and helps them work together. Each project keeps its own git history; Metaphor coordinates scaffolding, code generation, and runtime wiring across them.

Status

Foundation. The workspace skeleton, metaphor init, metaphor list, and plugin passthrough wiring are in place. Scaffolding (metaphor new) and a formal in-process plugin registry are on the roadmap — see docs/roadmap.md.

Install

curl -fsSL https://raw.githubusercontent.com/faridlab/metaphor-cli/main/install.sh | bash

One command, everything: the installer puts the metaphor binary on your machine and sets up the interactive terminal UI — installing a private Node.js runtime under ~/.metaphor/node (verified against Node's published checksums) when the machine has no Node.js >= 20, so it never touches an existing Node setup. Afterwards just run metaphor.

Other installers (npm, cargo install) are documented in docs/install.md.

30-second quickstart

metaphor init my-workspace   # clone the workspace template, stamped with the name
cd my-workspace
metaphor sync                # pull the pinned modules into modules/
metaphor doctor              # tooling + plugin health

Prefer to start from nothing? metaphor init --bare writes an empty metaphor.yaml in the current directory instead.

Then register projects by editing metaphor.yaml and run plugin commands like metaphor schema build or metaphor dev start. See docs/quickstart.md for the full walkthrough.

Interactive mode

Bare metaphor on a TTY opens the interactive terminal UI — a workspace overview (apps, environments, deployed versions, health), a searchable command browser — Enter runs a command with its defaults, o opens its options sheet — generated from the live command manifest. Requires the metaphor-ui npm package (npm install -g @metaphor/metaphor-ui, Node.js >= 20); without it, metaphor prints the install hint and falls back to the classic REPL.

metaphor repl still opens the line-based REPL — same subcommands, persistent history, shell-style quoting. In CI or under a pipe, bare invocation stays non-interactive — scripts and automation are unaffected.

Commands at a glance

Category	Command	What it does
Workspace	metaphor init [<name>]	Scaffold ./<name> from the workspace template (--template <URL> to override). No name or --bare writes an empty metaphor.yaml in the current directory.
	metaphor add <name>	Register a project (type, path, remote, depends_on) without hand-editing YAML.
	metaphor list	List registered projects.
	metaphor show projects / show project [<name>]	JSON-friendly inspection (add --json). <name> optional — auto-detects from cwd.
	metaphor info	Summarize the workspace and which project cwd is currently inside.
	metaphor doctor [--json]	Run diagnostic checks (paths exist, plugins installed, YAML parses, tools available). Exits non-zero on failures.
	metaphor ui or bare metaphor on a TTY	Interactive terminal UI: workspace overview, searchable command browser, per-command options sheet (requires metaphor-ui, falls back to the REPL).
	metaphor overview	Workspace at first sight: apps with versions/branches, environments with deployed versions, plugins, health. --json for scripts.
	metaphor manifest	Print the command tree as a manifest (text tree, or --json for tooling).
	metaphor repl	Enter the classic line-based REPL — persistent history, shell-style quoting, same subcommands.
	metaphor graph	Print the project dependency graph (tree or --json, optional --focus <name>).
Orchestration	metaphor <cmd> --all	Run a plugin command across every project.
	metaphor <cmd> --projects=a,b	Run across a chosen subset (topologically ordered).
	metaphor <cmd> --affected --base=main	Run only on projects whose files changed in git + their dependents.
	metaphor <cmd> --parallel=N	Fan out with N concurrent workers.
	metaphor <cmd> --continue-on-error	Keep going on failures; exit non-zero at the end.
	metaphor <cmd> --no-cache	Bypass the task result cache for this run.
Plugin passthrough	metaphor schema … / webapp …	Forward to metaphor-schema (schema parsing, webapp codegen).
	metaphor make / module / apps / proto / migration / seed …	Forward to metaphor-codegen.
	metaphor dev / lint / test / docs / config / jobs / docker / deploy …	Forward to metaphor-dev.
	metaphor agent …	Forward to metaphor-agent (install Claude Code skills and subagents into a project's .claude/).
Tooling	metaphor plugins [--json]	Show which plugin binaries this install can find + their versions.
	metaphor cache stats / cache clear	Inspect or clear the per-workspace task result cache.
	metaphor clean [--older-than=30d] [--apply] [--docker]	Remove stale build-artifact directories (target/, node_modules/, build/, etc.) per project type, and with --docker the dev stack's Docker build-cache volumes (data volumes untouched). Dry-run by default.
Deployment	metaphor build --all / --affected [--push]	Run docker build per project with consistent tagging.
	metaphor compose generate	Merge per-project compose.fragment.yml files into a workspace docker-compose.yml.
	metaphor env check	Validate every project's metaphor.env.yaml against the environment + workspace .env.
	metaphor docker <up|down|logs|ps|restart|pull|build>	Local docker-compose lifecycle. Passthrough to metaphor-dev; reads metaphor.deploy.yaml.
	metaphor deploy <push|rollback|status|logs|migrate|exec>	Remote deployment passthrough to metaphor-dev. deploy exec shells out to the workspace's infra project (deploy.sh / make deploy).

Every passthrough command accepts the orchestration flags above — without any of them, it behaves exactly like running the plugin binary directly. See docs/cli-reference.md for the full surface.

Documentation

• Install — every install method, env vars, upgrade, uninstall.
• Quickstart — first workspace, end to end.
• CLI reference — every subcommand, flag, and exit behavior.
• Workspace manifest — metaphor.yaml schema with examples.
• Plugins — the three plugin binaries and how discovery works.
• Plugin API — author guide for GeneratorPlugin and ToolPlugin.
• Architecture — how the four crates fit together.
• Roadmap — what's done, what's next.
• Contributing — build, test, add a subcommand.

Workspace layout

metaphor-cli/
├── Cargo.toml                       workspace root
└── crates/
    ├── metaphor-cli/                the binary + dispatcher
    ├── metaphor-workspace/          metaphor.yaml schema + I/O
    ├── metaphor-scaffold/           clones starter repos (planned)
    └── metaphor-plugin-api/         plugin trait surface

License

MIT.