# How to Manage Brand Identities with Archify's `brands` Command

> Effortlessly manage brand identities with Archify's brands command. Add vector badges to diagram nodes using built-in marks or external logos for reproducible rendering.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-29

---

**Archify's `brands` command lets you attach deterministic vector badges to diagram nodes by selecting from 107 built-in marks or capturing external logos with cryptographic pinning for reproducible rendering.**

The `tt-a1i/archify` repository treats **brand identity** as a first-class architectural primitive. By attaching brands to the primary nodes of architecture, workflow, sequence, data-flow, or lifecycle diagrams, you render compact, deterministic badges in the upper-right corner without overriding node topology or semantic meaning.

## Understanding Archify's Brand Identity System

In Archify, a **brand** functions as an immutable identity marker rather than decorative metadata. When attached to a node, it produces a provenance-backed vector mark that clearly identifies the underlying product or service.

### The Built-in Catalogue of 107 Marks

Archify ships with a bounded catalogue containing **107** provenance-backed vector marks. Each entry defines a **canonical ID**, human-readable **aliases**, and categorical metadata (**domain** and **category**). These definitions reside in [`archify/brand-marks/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/brand-marks/README.md) within the repository.

The catalogue enforces strict normalization: you reference brands by their canonical ID or any registered alias, ensuring consistent rendering across all diagram types.

## Querying Built-in Brands with the CLI

To inspect available brands, use the `brands` sub-command defined in `archify/bin/archify.mjs`. The CLI accepts search terms matching names, aliases, domains, or categories.

```bash

# List matching built-in brands with machine-readable output

node bin/archify.mjs brands "OpenAI" --json

```

*Implementation reference:* The usage string for this sub-command appears at lines 26-27 of `archify/bin/archify.mjs`.

When the query resolves to a built-in brand, Archify returns structured metadata:

```json
{
  "id": "openai",
  "aliases": ["OpenAI", "openai.com"],
  "domain": "ai",
  "category": "cloud"
}

```

The `--json` flag ensures machine-parseable output suitable for scripting or automated diagram generation.

## Capturing External Brand Assets

When diagrams reference products absent from the built-in catalogue, you must **capture** official brand assets before rendering. Archify performs safe, bounded fetches of remote logos and pins them to cryptographic digests.

### The Capture Workflow

Use the `brands capture` sub-command to fetch and pin external logos:

```bash

# Capture a brand from an official URL

node bin/archify.mjs brands capture "https://example.com/logo.png" --json

```

*Implementation reference:* The `brands capture` clause is defined in `archify/bin/archify.mjs` (lines 26-27), with runtime behavior documented in [`archify/references/brand-marks.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/brand-marks.md).

The command returns a JSON object containing:

- `url` — The original source URL
- `sha256` — Cryptographic digest of the fetched image
- `source` — Metadata including MIME type and byte size

Archify accepts **PNG, JPEG, WebP, and ICO** formats only. **SVG images are explicitly rejected** to prevent rendering inconsistencies.

### Validating Brand Integrity During Rendering

During diagram generation, Archify validates that the `brand` object's `sha256` digest matches the previously captured version. If the remote image changes or becomes unreachable, rendering fails with a diagnostic directing you to re-capture the brand.

This mechanism ensures **reproducible builds**: diagrams render identically regardless of external CDN changes or logo updates.

## Embedding Brands in Diagram Definitions

To attach a brand to a node, embed the captured object verbatim under the `brand` field in your diagram JSON:

```json
{
  "nodes": [
    {
      "id": "frontend",
      "type": "service",
      "label": "Web Front-End",
      "brand": {
        "url": "https://example.com/logo.png",
        "sha256": "a3f5c1…e9d4",
        "source": { "mime": "image/png", "bytes": 8421 }
      }
    }
  ]
}

```

The JSON schema at [`archify/schemas/brand.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/brand.schema.json) (referenced in [`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md)) validates this structure. During rendering, the badge appears in the upper-right corner of the node without displacing the semantic type icon or label.

## Best Practices for Brand Attribution

According to [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) (lines 70-73), follow these authoring guidelines:

1. **Never infer brands** from vague role descriptors like "database" or "cache". Always specify a built-in ID or explicit capture.

2. **Apply brands only to first-class components** — optional but explicit markers for products that constitute core architectural elements.

3. **Preserve semantic sigils** — The brand badge is additive; do not replace the node's type indicator with the logo.

Adhering to these rules prevents ambiguous visual encoding and maintains diagram accessibility.

## Summary

- **Archify manages brand identities** as first-class primitives with 107 built-in marks and support for external captures.
- **Query the catalogue** using `node bin/archify.mjs brands <query> --json` to resolve canonical IDs and aliases.
- **Capture external logos** with `brands capture <url> --json`, which pins images to SHA-256 digests for deterministic rendering.
- **Reference captured brands** by embedding the full JSON object (including `sha256`) in node definitions.
- **Validate integrity** automatically during rendering to prevent drift from upstream logo changes.

## Frequently Asked Questions

### How do I search for a specific brand in Archify's catalogue?

Use the `brands` sub-command with your search term and the `--json` flag. The CLI searches against canonical IDs, aliases, domains, and categories defined in [`archify/brand-marks/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/brand-marks/README.md). For example, `node bin/archify.mjs brands "Vercel" --json` returns the canonical ID and metadata if the brand exists in the 107-mark catalogue.

### What happens if I use a brand URL without capturing it first?

Rendering fails with a clear diagnostic error. Archify requires cryptographic pinning via `brands capture` before any external URL can appear in a diagram's `brand` field. This ensures the `sha256` digest exists for validation during the render phase.

### Can I use SVG images for brand badges in Archify?

No. Archify explicitly rejects SVG formats during the capture process. The `brands capture` command only accepts PNG, JPEG, WebP, or ICO files. This restriction prevents vector rendering inconsistencies and ensures deterministic rasterization across output formats.

### Where does Archify store the cryptographic digest for captured brands?

The digest resides in your diagram's node definition itself, within the `brand` object's `sha256` field. Archify does not maintain a global registry; instead, the captured JSON blob (including `url`, `sha256`, and `source` metadata) travels with the diagram source, making brand references portable and self-validating.