# How to Set Up and Use the Client Profile System for Multiple Brands

> Learn to set up and use the client profile system for multiple brands with a single installation. Isolate style guides for unlimited clients efficiently.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-09-08

---

**The Diagram Design client profile system for multiple brands enables a single installation to serve unlimited clients by storing each brand's style guide as an isolated profile in `~/.diagram-design/profiles/`, which you activate via project markers or explicit CLI commands.**

The cathrynlavery/diagram-design repository solves the multi-brand workflow problem through a robust profile management system defined in [`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md). Instead of maintaining separate software copies or constantly overwriting [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md), you create persistent client profiles that capture complete brand configurations with metadata headers. This guide covers initializing your profile library, creating brand snapshots, and switching between them using the CLI wrapper implemented in [`commands/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md).

## Initializing the Profile Library

Before creating your first client profile, ensure the library directory exists:

```bash
mkdir -p ~/.diagram-design/profiles

```

The system automatically generates a **built-in `default`** profile on first use. This pristine copy of the shipped [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) serves as your fallback baseline, so you do not need to create it manually. According to the reference implementation, the default snapshot initializes automatically when you first execute a save or load operation if it does not already exist.

## Creating Brand Profiles

To capture a new brand configuration, use the **save** verb. This serializes the current effective style guide into a named profile:

```bash
diagram-design profile save acme

```

The command executes the procedure defined in lines 10-21 of the profiles reference:

1. Reads the current effective style guide (working copy or previously loaded profile)
2. Prompts for **display name**, optional `source-url`, and optional `notes`
3. Validates the slug (`acme`) against the pattern `^[a-z0-9][a-z0-9-]{0,63}$`
4. Strips any existing metadata comment and prepends a fresh header with `created` and `updated` timestamps
5. Writes the file to `~/.diagram-design/profiles/acme.md`
6. Marks the profile **active** by writing `profile: acme` to the current directory's `.diagram-design` marker (after confirmation)

## Switching Between Client Profiles

Activate a specific brand profile using the **load** verb or the shorthand syntax:

```bash

# Shorthand (defaults to load)

diagram-design profile acme

# Explicit verb

diagram-design profile load acme

```

As implemented in lines 25-35 of [`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md), this command:

1. Validates the slug against the regex pattern
2. Reads the canonical profile file from the library
3. Runs the **current-schema structural check** to back-fill any missing rows from newer schema versions (see lines 99-104)
4. Replaces any existing `.diagram-design` marker with `profile: acme` (after confirmation), leaving the installed [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) untouched
5. If no marker exists, copies the full profile over [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) and offers to create a marker for persistence

## Managing Your Profile Inventory

### Listing All Profiles

View every saved brand configuration with:

```bash
diagram-design profile list

```

This command inspects `~/.diagram-design/profiles/` and renders a table showing each profile's **display name, slug, source-url, and updated date**, highlighting the currently active profile. See the *list* verb specification in lines 37-44 of the reference documentation.

### Inspecting Active Configuration

Check which profile is currently governing your diagrams:

```bash
diagram-design profile show

```

This outputs the active profile's name, slug, source file path, dates, and notes. If the working copy contains unsaved modifications, it reports `custom-unsaved`. If you have not yet created any snapshots, it displays `default (not yet snapshotted)`.

### Updating Existing Profiles

When you modify a style guide and need to overwrite an existing brand snapshot:

```bash
diagram-design profile update acme

```

This rewrites `~/.diagram-design/profiles/acme.md` with the **current effective style guide**, preserving the original `created` date while updating the `updated` timestamp. You may also edit `source-url` and `notes` during this operation (lines 50-57).

### Resetting to Factory Defaults

To discard customizations and return to the built-in default:

```bash
diagram-design profile reset

```

Equivalent to `diagram-design profile load default`, this command ensures [`default.md`](https://github.com/cathrynlavery/diagram-design/blob/main/default.md) exists and activates it, either by updating the project marker or overwriting the working copy (lines 59-65).

### Removing Obsolete Profiles

Delete a brand profile permanently:

```bash
diagram-design profile delete acme

```

After confirmation, this removes `~/.diagram-design/profiles/acme.md`. If any project marker still references the deleted slug, the system warns you and offers to reassign the marker to `default` or another existing profile (lines 67-73).

## Understanding Profile Resolution

When generating diagrams, the engine resolves the effective style guide through a specific hierarchy defined in lines 65-84 of the reference:

1. **Project marker** (`<project-root>/.diagram-design`) — If the file contains a valid `profile: <slug>` line, the system reads that profile directly
2. **Working copy header** — If the installed [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) begins with a profile header naming an existing slug, that profile becomes active
3. **Custom-unsaved detection** — If semantic roles or typography tokens differ from shipped defaults, the guide is classified as `custom-unsaved` and you are prompted to save it

This resolution order ensures that different brand projects never interfere with each other, even within the same repository checkout.

## Multi-Brand Workflow Example

Assume you manage three brands: **Acme**, **BetaCo**, and **Gamma Ltd**.

First, create the profiles:

```bash
diagram-design profile save acme
diagram-design profile save betaco
diagram-design profile save gamma-ltd

```

Then switch contexts per project:

```bash

# Acme project

cd /path/to/acme-project
diagram-design profile load acme

# BetaCo project

cd /path/to/betaco-project
diagram-design profile load betaco

```

Each directory now contains its own `.diagram-design` marker file specifying `profile: acme` or `profile: betaco`. When you run `diagram-design draw` in either location, the engine automatically applies the correct brand styling without additional flags.

## Summary

- **Initialize once**: Create `~/.diagram-design/profiles/`; the system handles the `default` snapshot automatically
- **Save brand configurations**: Use `diagram-design profile save <slug>` to capture snapshots with metadata headers
- **Switch contexts**: Use `diagram-design profile load <slug>` to write project markers that persist brand selection per directory
- **Maintain inventory**: Use `list`, `show`, `update`, and `delete` verbs to manage your profile library
- **Resolution priority**: The system checks project markers first, then working copy headers, ensuring isolated brand environments

## Frequently Asked Questions

### How does the Diagram Design client profile system store multiple brand configurations?

The system stores each brand as a separate Markdown file in `~/.diagram-design/profiles/<slug>.md`. Each file contains a complete copy of the style guide with a metadata header tracking the display name, creation date, source URL, and notes. This approach keeps brand configurations isolated from the core installation and allows instant switching without file conflicts.

### What is the difference between `diagram-design profile save` and `diagram-design profile update`?

The **save** verb creates a new profile from the current effective style guide, validating the slug and prompting for initial metadata. The **update** verb overwrites an existing profile file with the current working copy while preserving the original `created` date. Use `save` for new brands; use `update` when refining existing brand guidelines that have already been snapshotted.

### Why does the system use a `.diagram-design` marker file instead of modifying [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) directly?

The marker file (`<project-root>/.diagram-design`) containing `profile: <slug>` serves as a persistent pointer that survives repository clones and does not require modifying tracked files. This design allows the same repository to host multiple brand-specific subdirectories, each with its own marker, while keeping the actual [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) file generic or unmodified in version control.

### What happens if I delete a profile that is still referenced by a project marker?

The system detects the orphaned reference during the next resolution cycle and warns you that the marker points to a non-existent slug. It then offers to update the marker to `default` or another existing profile, preventing generation failures while maintaining project continuity.