# Where Are Diagram-Design Client Profiles Stored? File Paths, Format & CLI Commands

> Find where diagram design client profiles are stored at ~/.diagram-design/profiles/<slug>.md. Learn file paths, format, and CLI commands to manage your profiles.

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

---

**Diagram-design client profiles are stored in `~/.diagram-design/profiles/<slug>.md` as standalone Markdown files, keeping them isolated from the skill package to survive updates.**

The diagram-design skill persists named client profiles in a dedicated library outside the installed plugin. According to the `cathrynlavery/diagram-design` source code, this separation ensures user-created profiles remain intact through version upgrades and reinstalls. Each profile functions as a complete style-guide document with embedded metadata, accessible through a simple CLI interface.

## Profile Storage Location

### Directory Structure

All client profiles live in a single directory under the user's home folder:

- **Profile library root:** `~/.diagram-design/profiles/`
- **Individual profile file:** `~/.diagram-design/profiles/<slug>.md`

The slug serves as the unique identifier and filename base. The official specification in [`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md) (lines 9-13) defines this path structure and naming convention as the authoritative reference for profile storage.

### File Format

Each `.md` file contains:

1. A metadata comment block with fields: `slug`, `name`, `source-url`, and additional attributes
2. A complete [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) document body

This format allows profiles to be version-controlled, manually edited, or shared between systems while maintaining compatibility with the diagram-design engine.

## How the Profile System Works

The diagram-design engine uses a three-stage workflow for profile management:

### 1. Creating and Saving Profiles

The `save <slug>` command writes the current effective style guide to `~/.diagram-design/profiles/<slug>.md`. This captures the active configuration as a reusable template.

```bash

# Save current style guide as "acme" profile

diagram-design save acme

```

### 2. Project-Level Profile Selection

A marker file `.diagram-design` in the project root determines which profile loads for that workspace. The file contains a single line:

```

profile: <slug>

```

When the engine detects this file, it reads the corresponding profile from the library. This allows different projects to use different client branding guidelines without global switches.

### 3. Profile Lifecycle Operations

All management verbs operate directly on files in `~/.diagram-design/profiles/`:

| Command | Action | Target File |
|---------|--------|-------------|
| `list` | Enumerate all saved profiles | Scans directory |
| `show` | Display active profile contents | Reads `<slug>.md` |
| `update <slug>` | Overwrite with current style guide | Rewrites `<slug>.md` |
| `delete <slug>` | Remove permanently | Deletes `<slug>.md` |

The `default` profile operates differently—it generates from a built-in snapshot rather than a persisted file.

## Complete CLI Reference

```bash

# List all saved client profiles

diagram-design list

# Save current effective style guide as new profile

diagram-design save acme

# Activate profile for current project (creates/updates .diagram-design marker)

diagram-design load acme

# Alternative syntax:

diagram-design switch acme

# Display details of currently active profile

diagram-design show

# Update existing profile after style guide modifications

diagram-design update acme

# Remove profile permanently

diagram-design delete acme

```

All commands read from or write to `~/.diagram-design/profiles/<slug>.md` except where noted.

## Key Source Files

| Path | Purpose |
|------|---------|
| [`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md) | Definitive profile storage specification, path definitions, and command documentation |
| [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) | General skill description with profile handling overview |
| [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md) | High-level introduction to the diagram-design ecosystem |

## Summary

- **Profile location:** `~/.diagram-design/profiles/<slug>.md` in the user's home directory
- **Isolation from updates:** Profiles survive skill package upgrades because they live outside the installation directory
- **Project binding:** `.diagram-design` marker files in project roots link workspaces to specific profiles
- **Direct file access:** The CLI operates on plain Markdown files, enabling manual editing and version control

## Frequently Asked Questions

### Can I manually edit a profile file?

Yes. Because profiles are standard Markdown files at `~/.diagram-design/profiles/<slug>.md`, you can edit them directly with any text editor. Run `diagram-design update <slug>` afterward if you want to refresh the engine's cached view, though the system typically reads fresh on each invocation.

### What happens to profiles when I reinstall diagram-design?

Nothing. The profile library location outside the skill package means `pip install` upgrades, `git pull` updates, or complete reinstalls leave your `~/.diagram-design/profiles/` directory untouched. This design intentionally separates user data from application code.

### How do I share profiles between machines?

Copy the `<slug>.md` files from `~/.diagram-design/profiles/` on one machine to the same directory on another. The metadata header ensures proper registration. For team environments, consider committing these files to a shared repository and symlinking them into each developer's profile library.

### Why does the `default` profile behave differently?

The `default` profile is generated on first use from an internal snapshot rather than a persisted file. This guarantees a working baseline even when no custom profiles exist. Once you `save` a custom profile, you have full file-based control over your configuration.