CLI

Installation

All examples below use the installed executable:

Canonical command tree

This tree is exhaustive for built-in commands. There are no public command aliases, deprecated routes, or package-specific alternatives. In particular, maintainer commands are available only below di-framework mx. The single sanctioned extension point is the installed-extension namespace: a top-level token that is not a built-in command may dispatch to an installed CLI extension.

The command paths and conventions on this page are the stable public contract.

One executable

@di-framework/cli publishes one bin: di-framework. Application builds, skill indexing, OpenAPI generation, agent operations, and monorepo maintenance all route through the canonical command tree above. Feature packages remain programmatic libraries and do not publish package-specific executables. That includes CLI extensions: an extension package must not declare a bin; its commands run through di-framework <name>.

Neutral skill discovery uses .agents/skills and ~/.agents/skills. No non-neutral path is consulted implicitly.

App commands

init installs @di-framework/tsc and @di-framework/cli by default, sets plugins: [{ "transform": "@di-framework/tsc" }], and wires build and check scripts to di-framework. Runtime checks are injected during emit. Development runs source with Bun and does not perform emit-time checks. The first transformed build needs a Go toolchain; see Runtime type checks.

Skills index commands

The five index leaves delegate to the typed @di-framework/ai-utils operations; the CLI only maps arguments and presents their results:

The default index path is .di-framework/skills-index.json. Text output summarizes the typed package result; JSON mode returns that result in data. Validation drift and query abstention exit 1. Invalid options, missing inputs, and invalid indexes exit 2; dependency, embedding, write, and unexpected operation failures exit 3.

Validate skill catalogs

skills validate uses the same neutral source resolution and validateSkillCatalog API as application code:

Text mode prints a summary and source-aware diagnostics. JSON data contains valid, skillCount, and the typed diagnostics without skill bodies. Valid catalogs exit 0, catalogs with error findings exit 1, malformed CLI configuration exits 2, and unavailable packages or unexpected failures exit 3.

Generate HTTP OpenAPI

--controllers is required and repeatable. --output may be supplied once and defaults to openapi.json. The handler delegates controller loading, OpenAPI 3.1 generation, and explicit file writing to @di-framework/http. JSON data contains controllerModules, outputPath, and bytes. Usage failures exit 2; package loading, controller loading, generation, and writing failures exit 3.

Agent configuration commands

All four leaves delegate agent-configuration decisions to typed @di-framework/ai-utils APIs. They only discover the neutral AGENTS.md, .agents/skills, ~/.agents/skills, and root .aiignore conventions automatically. An audit may report known vendor assets as migration opportunities, but those assets are never loaded as active configuration and no command creates a vendor-specific path or compatibility adapter.

Actor commands

actor inspects and resets local @di-framework/actors SQLite storage. It does not start a runtime.

inspect requires a positional type or identity (exit 2 if missing). reset/clean require --actor, --namespace, or --all. Missing @di-framework/actors exits 3 (ACTORS_PACKAGE_UNAVAILABLE). Not found exits 1 (ACTOR_NOT_FOUND).

JSON data:

• list: { namespace, baseDir, total, actors: [{ actorId, namespace, actorType, actorKey, status, runningCalls, pendingCalls, storagePath, failedMigration }] }

• inspect: the same identity fields plus methods, failedMigration, and state only with --show-state

• reset/clean: { scope, deactivatedCount, deletedFiles, success }

Database migration commands

migrations delegates discovery and execution to @di-framework/repo.

JSON data is { binding, isUpToDate, applied, pending } for status and { binding, applied, pending, dryRun, durationMs } for execute. A requested --binding that does not match discovered migrations exits 2 (MIGRATION_BINDING_MISMATCH). Connect and runner failures exit 1.

Durable queue commands

queue inspects the SQLite job table used by @di-framework/queues. It does not start a worker.

Database path: --db → DI_QUEUE_DB → existing .di-framework/queue.db → existing queue.db → else .di-framework/queue.db. JSON data is { queues } for list, { jobs } for inspect, and { retried } for retry. Missing @di-framework/queues exits 3 (QUEUES_PACKAGE_UNAVAILABLE). Invalid options exit 2.

Maintainer commands

The mx group is only for the di-framework monorepo:

Top-level maintainer aliases are not part of the public command tree.

Extensions

Optional capabilities ship as installable extensions so the core CLI stays lean. Installing an extension adds one top-level command named after it:

<spec> is an npm package name with an optional version range (wasmcloud, @di-framework/cli-plugin-wasmcloud@^5). A bare <name> resolves to the canonical @di-framework/cli-plugin-<name> package. Extensions are ordinary npm packages named by convention:

• @di-framework/cli-plugin-<name> — canonical, first-party.

• di-framework-cli-plugin-<name> and @<scope>/di-framework-cli-plugin-<name> — third-party.

The store is a private package directory at ~/.di-framework/extensions, overridden by DI_FRAMEWORK_EXTENSIONS_DIR. An extension package present in the current project's node_modules overrides the user-global installation, so projects can pin an exact extension version as a normal dependency.

Dispatch rules:

• Built-in commands always win. Extension resolution only runs for top-level tokens that are not in the canonical tree, and installing an extension whose name collides with a built-in command or help is rejected.

• The extension manifest — the package default export, built with defineExtension from @di-framework/cli-extension — is structurally validated before its command tree is mounted; an invalid or misnamed manifest is rolled back at install time and reported with a stable error code at dispatch time.

• Mounted extension commands inherit this page's contract in full: help forms, the JSON envelope, and the exit-status table all behave exactly as for built-in commands.

Root help lists installed extensions alongside the built-in tree. The first available extension is wasmCloud deployment; authors of new extensions start from @di-framework/cli-extension, which provides the manifest contract, the command-node types, and CommandFailure.

Naming and help

• Command names are lowercase English words in kebab-case. Groups use nouns and operations use imperative verbs.

• di-framework help, di-framework --help, and di-framework -h show root help. Every group and leaf accepts the same three help forms for that node.

• Explicitly requested help goes to standard output with exit status 0. An incomplete group writes its help to standard error with exit status 2.

• Help includes usage, available children or options, and a short description.

• Unknown commands identify the invalid token and show the nearest group help. Leaf handlers reject unknown options, missing option values, duplicate single-value options, and extra positional arguments. Arguments are never silently ignored.

• Global --json is accepted before or after the canonical command path. Command-specific options follow the complete command path.

Text, JSON, and errors

Normal text and explicitly requested help go to standard output; errors go to standard error. In JSON mode the command writes exactly one JSON value followed by a newline to standard output and no presentation text.

A successful result has this envelope:

command is the canonical space-separated path. data is the typed package result or a documented command-specific object. A failure omits data and uses a stable error code:

details is optional. JSON failures use standard output so automation has a single parseable channel; unexpected internal diagnostics may also use standard error. JSON property names and enum values are a stable API. JSON output never includes colors, icons, or environment-dependent formatting.

Exit status

Package ownership

Command handlers return results or throw typed command failures. They do not call process.exit(), write through global console, or translate domain results into exit statuses. Tests at the CLI boundary must prove delegation to package APIs. If a workflow cannot be exposed without copying package internals, its typed package API is extended first.

Next steps

• Installation - Core package and CLI setup

• Quick Start - Basics after scaffolding

• wasmCloud - Build and deploy apps as WebAssembly components

• wasmCloud backing services - wasmcloud service create/list/get/delete/classes for tenant Redis/NATS requests

• Kubernetes with di-framework-kube - Separate platform CLI and live example deployment workflow

• HTTP Router - HTTP routing, OpenAPI generation, and static assets

• Private service bindings - Named in-process contracts (no dedicated CLI command)

• Scheduling - @Cron (discovered by wasmcloud build, no cron group)

• Queues - Durable jobs and queue list/inspect/retry

• Repositories - Decorator, SQL, and manifest migrations

• Actors - Local runtime, persistence, and actor commands

• Agents - Skills, plugins, and skill-index programmatic APIs

• Runtime type checks - Emit-time transforms wired by init