Understanding Archify's Brand Mark Operations: CLI Reference and Usage

Archify's brand mark operations provide a three-command CLI interface—list, capture, and show—for managing SVG logo catalogues that render recognizable brand icons alongside nodes in architecture diagrams.

Archify, maintained in the tt-a1i/archify repository, includes a built-in brand mark catalogue that simplifies adding visual identifiers like OpenAI or GitHub logos to technical diagrams. These brand mark operations enable developers to query existing assets, import custom logos from public URLs, and inspect SVG definitions through the archify brands sub-command interface.

Core Brand Mark CLI Commands

The brand mark functionality exposes three primary operations through the archify brands sub-command. Each command supports a --json flag for machine-readable output suitable for CI/CD pipelines and automation scripts.

Listing Available Brand Marks

The list operation returns the complete catalogue of built-in brand marks, including their identifiers, labels, and SVG data.

# Human-readable list of all brand marks

archify brands list

# JSON output for programmatic access

archify brands list --json

The JSON output follows the schema {"marks":[{"id":"openai","label":"OpenAI","svg":"<svg …>"} …]}.

Capturing Custom Brand Marks

The capture operation retrieves logo assets from public URLs and creates new brand-mark presets, enabling organizations to add proprietary icons to their local catalogue.

# Capture a logo from a company homepage

archify brands capture https://example.com --json

This command returns a confirmation object: {"brand":"example","evidence":{"status":"preset","source":"https://example.com"}}.

Showing Individual Brand Definitions

The show operation retrieves the complete definition for a specific brand identifier, useful for debugging SVG assets or verifying catalogue entries.

# Display the OpenAI brand mark definition

archify brands show openai --json

The output includes the id, label, and complete svg string: {"id":"openai","label":"OpenAI","svg":"<svg …>"}.

Embedding Brand Marks in Diagrams

Once a brand mark exists in the catalogue, you can attach it to diagram nodes through the JSON Intermediate Representation (IR) or HTML attributes.

JSON IR Configuration

Add the brand identifier to the node's meta object:

{
  "nodes": [
    {
      "id": "gpt-service",
      "label": "GPT Service",
      "type": "service",
      "meta": { "brand": "openai" }
    }
  ]
}

When rendered, Archify automatically places the OpenAI logo beside the "GPT Service" node label.

HTML Rendering and CSS Classes

During rendering, Archify applies the .brand-mark CSS class to the SVG element, along with helper classes .brand-mark-badge and .brand-mark-frame. The viewer attaches the attribute data-node-brand="<brand-id>" to identify which logo to display. This implementation requires no additional JavaScript for logo placement.

Source Code Implementation

The brand mark operations are implemented in scripts/generate-brand-marks.mjs, which handles the CLI parsing, URL fetching, and SVG storage logic. Quality assurance resides in scripts/package-smoke.mjs, which validates that core marks like openai exist and that capture operations resolve correctly.

Documentation for the brand-mark contract and agent usage guidelines appears in archify/SKILL.md. The runtime HTML generation that applies .brand-mark classes and renders the SVG placement is visible in generated/maka-regenerated.workflow.html around line 1760.

Summary

• Archify provides three brand mark operations—list, capture, and show—accessible via the archify brands sub-command.
• All commands accept a --json flag for machine-readable output compatible with automation workflows.
• Custom logos are imported using archify brands capture <url>, adding proprietary assets to the local catalogue.
• Diagram nodes reference brands through the meta.brand property in JSON IR or the data-node-brand HTML attribute.
• Rendering applies standard CSS classes (.brand-mark, .brand-mark-badge) without requiring additional JavaScript.

Frequently Asked Questions

How do I add a custom company logo to Archify diagrams?

Use the archify brands capture command with your company's public logo URL. For example, archify brands capture https://example.com/logo.png --json creates a preset that you can reference in node metadata using "brand": "example" in the JSON IR.

What is the difference between default and --json output formats?

The default output provides human-readable tables suitable for terminal inspection, while the --json flag emits structured data including complete SVG strings, which scripts and build pipelines can parse programmatically without text parsing.

Where are brand mark operations implemented in the Archify source code?

The CLI logic lives in scripts/generate-brand-marks.mjs, which implements the capture, list, and show functionality. Test coverage ensuring catalogue integrity exists in scripts/package-smoke.mjs, and the rendering contract is documented in archify/SKILL.md.

How does Archify render brand marks without JavaScript?

The viewer generates static HTML with CSS classes like .brand-mark and .brand-mark-frame, applying the data-node-brand attribute to position SVG logos during the initial render. This approach embeds the logos directly into the generated HTML without requiring client-side script execution.

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