@acid-cat/cli

The AcidCat command line. npm package: @acid-cat/cli. It gives the acid-cat command. Use it at build time, in CI or by hand, to check catalogs and to test implementations. Do not use it in an application at run time.

acid-cat check [--strict] <catalog.json ...>  # check catalogs
acid-cat format [--write] <catalog.json ...>  # write catalogs in canonical form
acid-cat view <catalog.json> <target>         # write the view of one target
acid-cat conform --mcp <url> --mcp-stdio "<command>" --http <url> --cli "<command>" --webmcp <url> [--deadline <ms>]  # test an implementation

Install it as a development dependency, and run it with pnpm exec acid-cat …:

pnpm add -D @acid-cat/cli

It needs Node.js 24 or later. acid-cat conform --webmcp <url> also needs Playwright and Chromium.

check

check tests a catalog against schemas/catalog.schema.json and against the catalog rules that the schema cannot express.

• An error is a broken rule. Example: an audience that names an unknown target.
• A warning is a broken recommendation. Examples: a file that is not in canonical form, or a member with no x- prefix.

The exit code is 0 if there are no errors. It is 1 if there are errors. With --strict, warnings also give the exit code 1.

format

format writes a catalog in canonical form. Use it for catalogs that a catalog library did not write: Pkl output, generated files, or files that you edit by hand.

conform

conform tests a running implementation of the conformance fixture through its bindings (see Conformance):

• MCP through HTTP: --mcp <url>. The official MCP client, with revision 2026-07-28, for tools and outcomes; raw requests for rejections.
• MCP through stdio: --mcp-stdio "<command>", or mcpStdio in code. The checks start the server as a process. The official MCP client tests the tools and outcomes two times: with revision 2026-07-28, and with the initialize handshake of revision 2025-11-25. It also tests notifications/tools/list_changed and notifications/cancelled. Raw lines test the version negotiation, a line that is not JSON, a standard output with only JSON-RPC messages, and the end of standard input.
• HTTP and CLI: each outcome, each kind of call failure, availability, and rejections. For the CLI, also each kind of flag, including a repeated flag that gives one item of an array for each occurrence, or the whole array as JSON text, and the usage line of each command. An interrupt (SIGINT) during a call that holds gives exit code 130.
• WebMCP: the checks act as the WebMCP host. --webmcp <url> opens a page that serves the app target in Chromium, through Playwright, with a test modelContext. Install Playwright to use it: pnpm add -D playwright, then pnpm exec playwright install chromium. In code, webmcp can also be a function that installs the implementation on a host in the same process.
• Properties: with fast-check, through MCP with each transport and through HTTP: concurrent calls each get exactly their own outcome, and a cancellation changes only its own call.

The checks wait for states that they can observe, not for times. Before a check cancels a call to fixture.hold, it waits until fixture.held gives the key of the call, or, for the CLI, until the marker file of the call exists. Each check has one deadline: --deadline, or deadline in code, in milliseconds. The default is 30 000. A check that does not settle before its deadline fails with "did not settle", and the check stops what it started. This cleanup has a deadline of the same length, so conform always returns. The deadline never makes a check pass.

The exit code is 1 if a check fails. Both AcidCat cores run conform in their tests. In code, use conform() and serve() from @acid-cat/cli. createTestHost() gives the WebMCP host of the checks.

Implementation

The command line is an Effect program that uses effect/cli. It validates catalogs with Effect Schema. It imports schemas/catalog.schema.json and each schema in the catalog as Effect schemas.

| File | Contents | | --- | --- | | src/catalog.ts | The catalog rules, views and bundling | | src/main.ts | The commands | | src/conform/ | The conformance checks, and serve, which serves web handlers on a local port | | conformance/ | The conformance fixture, in Pkl and in JSON | | test/ | Tests. Run them with moon run cli:test | | test/fixtures/ | The catalog of the tests: a bakery, in canonical form |

The canonical writer comes from @acid-cat/catalog.