Complete Guide to Archify CLI Commands: Usage and Examples

The Archify CLI provides eleven primary commands—including render, validate, generate:viewer, and test—that allow you to process JSON-IR architecture files, validate schemas, regenerate viewer bundles, and execute the full test suite from the terminal.

The command-line interface for the tt-a1i/archify repository ships as a Node.js binary that processes JSON-IR (Intermediate Representation) architecture descriptions. Whether you are generating interactive diagrams, validating structural integrity, or building the viewer bundle, the archify CLI exposes all core functionality through predictable sub-commands defined in the source tree.

Installing the Archify CLI

The CLI entry point is declared in [archify/package.json](https://github.com/tt-a1i/archify/blob/main/archify/package.json) under the bin field, which maps the archify command to ./bin/archify.mjs. After cloning the repository and running npm install, the binary becomes available in your node_modules/.bin directory or globally if you link the package.

npm install
npm link  # Optional: makes 'archify' available globally

Core Archify CLI Commands

The CLI implementation in bin/archify.mjs uses Node’s built-in process.argv parser to dispatch to the appropriate handlers. Below are the available sub-commands organized by functional category.

Rendering and Validation

archify render <input-file> [options]

Transforms a JSON-IR architecture description into an interactive HTML viewer or static image asset. This command reads the IR file specified by <input-file> and outputs the rendered diagram to the destination provided by the --out flag.

archify render examples/archify-repo.architecture.json --out diagram.html

archify validate <input-file>

Validates a JSON-IR file against the generated schema to ensure structural correctness. This command is essential for CI pipelines to verify that architecture definitions meet the required specification before rendering.

archify validate examples/archify-repo.architecture.json

Generator Commands

The generate:* namespace contains utilities for rebuilding project assets and validators.

archify generate:viewer

Regenerates the viewer bundle after making source changes. The implementation resides in scripts/generate-viewer.mjs, which compiles the interactive visualization components.

archify generate:viewer

archify generate:brand-marks

Produces the brand-mark SVG assets used in documentation and output. This command wraps the logic found in scripts/generate-brand-marks.mjs.

archify generate:brand-marks

archify generate:validators

Creates the JSON-IR validator scripts from the current schema definitions. The underlying script is located at scripts/generate-validators.mjs.

archify generate:validators

Build Utilities

archify build:gallery

Compiles the example gallery showcased in the project documentation. This command aggregates sample architecture files into a browsable collection.

archify build:guide

Builds the documentation guide page, processing markdown and assets into the final static site output.

archify build:start

Builds the starter page template used for new architecture projects.

Testing and Diagnostics

archify test

Executes the full test suite, including viewer functionality checks, brand-mark validation, validator integrity tests, and release-identity verification. This command invokes multiple test runners, including the golden-file tests defined in test/golden.mjs.

archify test

archify version

Prints the current Archify version number as defined in the package manifest.

archify help

Displays the help overview listing all available commands, their arguments, and basic usage examples.

CLI Architecture and Implementation Details

The command dispatcher lives in bin/archify.mjs, which parses process.argv to determine the requested sub-command. Unlike heavier frameworks such as Commander or Yargs, the Archify CLI uses lightweight argument inspection to minimize dependency overhead. Each sub-command maps to a specific module in the scripts/ directory or an internal handler for core operations like render and validate.

The binary declaration in archify/package.json ensures that when you invoke archify from the terminal, Node.js executes bin/archify.mjs with the correct module resolution context.

Summary

• The Archify CLI exposes eleven commands through the archify binary defined in archify/package.json.
• Rendering (render) and validation (validate) handle JSON-IR architecture files.
• Generator commands (generate:viewer, generate:brand-marks, generate:validators) rebuild project assets using scripts in the scripts/ directory.
• Build commands (build:gallery, build:guide, build:start) compile documentation and example collections.
• The test command runs the comprehensive test suite including golden-file verification in test/golden.mjs.
• The CLI parser in bin/archify.mjs uses Node’s native process.argv inspection for lightweight command dispatch.

Frequently Asked Questions

How do I install the Archify CLI locally?

Clone the tt-a1i/archify repository, run npm install to fetch dependencies, and optionally execute npm link to register the archify binary globally. The CLI entry point at bin/archify.mjs becomes callable through your shell once linked.

What is the difference between archify render and archify validate?

The render command transforms JSON-IR files into interactive HTML viewers or static images for visualization, while the validate command checks the structural integrity of the same JSON-IR files against the project schema without producing visual output. Use validate in CI pipelines to catch syntax errors before invoking render.

Which source files implement the Archify CLI commands?

Command dispatch logic resides in bin/archify.mjs, which uses Node’s process.argv parser to route requests. The generate:* sub-commands delegate to specific modules: scripts/generate-viewer.mjs handles viewer bundle regeneration, scripts/generate-brand-marks.mjs creates SVG assets, and scripts/generate-validators.mjs builds validation scripts. Test execution includes test/golden.mjs for comprehensive verification.

Can I use the Archify CLI without installing it globally?

Yes. You can execute the CLI directly using Node.js by running node bin/archify.mjs <command> from the repository root, or use npx if the package is published to the npm registry. The archify/package.json file defines the binary mapping, ensuring local execution respects the project's dependency tree.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}