Diagent Cli

@diagent/cli

Command-line tool to encode and decode Diagent shareable diagram URLs. Designed for agents (Claude Code, Cursor) and humans alike.

By default, `diagent encode` produces a **short URL** like `https://diagent.dev/d/abcdefghij` (~31 chars, constant size regardless of diagram complexity). This works by calling the Diagent backend's `POST /api/s` endpoint, which stores the Mermaid in Cloudflare KV and returns a content-addressed short ID.

If the backend is unreachable (dev, offline, rate-limit, Cloudflare outage), `diagent encode` **automatically falls back** to an inline URL of the form `https://diagent.dev/?code=`, which carries the full Mermaid source in the `code` query parameter. The feature never fully breaks — worst case, you get a longer URL and a stderr notice. Pass `--inline` to skip the backend entirely and always produce the inline format.

Install

**From npm:**

npx -y @diagent/cli --help
# or install globally
npm install -g @diagent/cli

**From source (contributors):**

cd cli
npm install
npm run build
npm link     # puts `diagent` on your global PATH

Usage

diagent encode [FILE] [--base-url URL] [--inline]
                                          Encode Mermaid from FILE or stdin -> URL on stdout
                                          (tries backend short URL, falls back to inline)
diagent decode                       Decode inline ?code= URL -> Mermaid source on stdout
diagent decode -                          Decode URL read from stdin
diagent --help                            Show help
diagent --version                         Show version

**Encode from stdin (produces a short URL):**

cat flow.mmd | diagent encode
# https://diagent.dev/d/kwtsgx5o24

**Encode from a file:**

diagent encode flow.mmd

**Force inline format (skip backend):**

diagent encode flow.mmd --inline
# https://diagent.dev/?code=GYGw9g7gxg...

**Encode against a