Asterdoc logo

@asterdoc/cli

[![Asterdoc documentation](https://img.shields.io/badge/Documentation-Asterdoc-red.svg)](https://docs.asterdoc.com?utm_source=github&utm_medium=cli) [![Follow on Twitter](https://img.shields.io/twitter/follow/asterdoc?style=social)](https://x.com/asterdoc)
Asterdoc treats documents as structured, machine-readable artifacts. The CLI initializes projects, manages artifacts and registries, validates data, and runs local document workflows. ## Installation Requires Node.js 24.14 or newer. ```bash npm install -g asterdoc ``` You can also run it without a global install: ```bash npx asterdoc --help ``` `asterdoc` and `@asterdoc/cli` publish the same CLI and both register the `asterdoc` executable. Install one package, not both. ## Quick start ```bash asterdoc init my-project cd my-project asterdoc registry add @acme https://registry.acme.com asterdoc search "lease agreement" asterdoc add @acme/example-form asterdoc list asterdoc show @acme/example-form ``` A registry reference is `@namespace/name[/edition][@version]`. With no edition and no version, `asterdoc add` installs the release the registry states as its default: the current edition, latest version. ```bash asterdoc add @acme/w-9 # current edition, latest version asterdoc add @acme/w-9/2024-03 # latest version of edition 2024-03 asterdoc add @acme/w-9@1.0.0 # version 1.0.0 of the current edition asterdoc add @acme/w-9/2024-03@1.0.0 # one edition, one version ``` `asterdoc add` checks each file against the SHA-256 in the registry manifest and records the installed edition and version in `.asterdoc/lock.json`. `asterdoc search` shows every edition and version of an artifact. To publish a registry, list your artifact source files in `registry.config.json` and compile it. Each source file is one release; files with the same `name` become the editions and versions of one artifact. ```bash asterdoc registry make # writes registry.config.json asterdoc registry catalog add forms/w-9.json # adds a source file asterdoc registry compile --output dist # writes dist/registry.json and each release ``` `registry compile` writes each release to `///` (or `//` for an artifact with no editions). The default version is the highest version that is not a pre-release. The default edition is the one that started last and not after today. State another default in `registry.config.json`: ```json { "name": "acme", "sources": ["forms/w-9-2024-03.json", "forms/w-9-2018-10.json"], "defaults": { "w-9": { "currentEdition": "2018-10" } }, "tags": { "w-9": ["tax"] } } ``` `asterdoc init` prompts for project details. For a non-interactive setup, pass `--yes` and `--name`: ```bash asterdoc init my-project --yes --name "My Project" ``` ## Global options ```text -V, --version output the version number -h, --help display help for command ``` Run `asterdoc --help` for command-specific arguments and options. The [CLI command reference](https://docs.asterdoc.com/cli/commands) documents the full command set. ## Project files An Asterdoc project contains `asterdoc.json` and a `.asterdoc` directory. Installed artifacts and their files are recorded in `.asterdoc/lock.json`; commit the lock file with your project. ## Related packages - [`@asterdoc/sdk`](../../packages/sdk) - [`@asterdoc/core`](../../packages/core) - [`@asterdoc/schemas`](../../packages/schemas) - [`@asterdoc/render`](../../packages/render)