---
name: atelier
description: Use the `atelier` CLI to read, write, search, and lint a folder of HTML/Markdown artifacts as a vault. Trigger when the user mentions "Atelier", working with a folder of HTML artifacts, agent-built artifact collections, or asks to inspect/search/create files inside a vault directory. The CLI is on PATH globally — invoke via Bash.
---

# Atelier CLI

`atelier` is a globally-installed CLI for inspecting and modifying a vault — a folder of HTML and Markdown artifacts that link to each other. It's the agent-side surface of the Atelier desktop app; same operations, no GUI needed.

Install it once with `npm install -g @codependentai/atelier`. Every JSON output includes `schemaVersion: 1` — the contract is stable.

## When to use this

- The user has a folder of HTML/Markdown artifacts and wants to navigate, audit, or modify it programmatically
- You need to create, update, move, rename, duplicate, or delete files inside a vault
- You need to search for a phrase across a vault's content
- You need to lint a vault for missing links, missing titles/descriptions, orphan files, or HTML parse errors
- You need to watch a vault for changes (NDJSON event stream)
- You need to scaffold a new file from a template

## Read commands

```bash
atelier index <vault> [--json]
atelier inspect <vault> <file> [--json]
atelier context <vault> --file <file> [--include-source] [--json]
atelier search <vault> <query> [--in body,title,tags,headings|all] [--limit N] [--case-sensitive] [--json]
atelier link-check <vault> [--json]
atelier lint <vault> [--json]
atelier templates <vault> [--json]
```

- `index` — full file listing with titles, headings, metadata, links, backlinks, graph
- `inspect` — single file detail (outgoing/backlinks/missing)
- `context` — file + outgoing + backlinks + related; pass `--include-source` to embed the file content (good for priming an edit)
- `search` — substring search across selected fields. `--in body,title,tags,headings` or `--in all`. Default fields: all. Returns ranked snippets with byte index.
- `link-check` — just the missing-link audit
- `lint` — link-check + missing-title + missing-description + orphan files + HTML parse errors. Returns `{ ok, fileCount, linkCount, issues: [{file, kind, message}] }`. Kinds: `missing-link | missing-title | missing-description | orphan | parse-error`.
- `templates` — list templates available in the vault's `.htmlvault/templates/` directory.

## Write commands

```bash
atelier init <path> [--name "Display Name"] [--no-welcome] [--json]
atelier create <vault> <path> [--title T] [--template name] [--content C | --from-stdin] [--json]
atelier create <vault> --title T [--format html|md] [--template name] [--json]
atelier import <vault> <file...> [--target <dir>] [--json]
atelier update <vault> <file> [--content C | --from-stdin] [--json]
atelier move <vault> <from> <to> [--json]
atelier rename <vault> <file> <new-name> [--json]
atelier duplicate <vault> <file> [--json]
atelier delete <vault> <file> [--json]
atelier mkdir <vault> <folder> [--json]
```

- `init` creates a new vault folder with `.htmlvault/config.json` and a seed `index.html` (suppress with `--no-welcome`)
- Content for `create` and `update` comes from `--content "..."` (short), `--from-stdin` (pipe), or omitted on `create` to use a template (per `--template` flag, `defaultTemplate` from config, or built-in fallback)
- `--template <name>` on `create` resolves a template from `<vault>/.htmlvault/templates/<name>.html|.md` and substitutes `{{title}}` / `{{date}}` placeholders before writing
- `import <vault> <file...>` copies external HTML/Markdown files into the vault, optionally to a target subdirectory; collisions auto-rename
- `delete` moves to OS trash where supported, falls back to hard delete
- `rename` changes the basename only — use `move` to relocate across folders
- `duplicate` adds `-copy[-N]` suffix automatically, never overwrites
- `mkdir` is idempotent against the path; throws if the folder already exists
- All write commands return `{ ...op-specific, vault: { vaultName, rootPath, fileCount, linkCount, generatedAt } }` summary instead of dumping the full index

## Stream

```bash
atelier watch <vault>
```

Emits NDJSON events on stdout: `{schemaVersion, type: "added"|"changed"|"removed", relativePath, generatedAt}`. Plus a `watch:start` event on launch. SIGINT to stop.

## Prompt scaffolds

```bash
atelier prompt create <vault>
atelier prompt revise <vault> --file <file>
```

Generate vault-aware prompt strings for human-in-the-loop workflows.

## Vault config & templates

A vault may have a `.htmlvault/` directory with config and templates (the directory name `.htmlvault` is the on-disk convention; left as-is for backward compatibility):

```
<vault>/
  .htmlvault/
    config.json
    templates/
      decision-log.md
      explainer.html
      report.html
```

`config.json` shape:

```json
{
  "vaultName": "Display name override",
  "defaultTemplate": "decision-log",
  "ignoredPaths": ["drafts/"]
}
```

Template files use `{{title}}` (replaced with the new file's title) and `{{date}}` (`YYYY-MM-DD`).

When creating a new file:
1. If `--template <name>` is passed, that wins
2. Else, `defaultTemplate` from `config.json` is used
3. Else, built-in template (basic HTML stub or markdown frontmatter)

Always run `atelier templates <vault>` first when creating multiple files to see what scaffolds exist.

## Concrete workflows

**Inspect what's in a vault before editing:**
```bash
atelier index /path/to/vault --json
```
Use the result to know all the files, their titles, and the link graph before deciding what to change.

**Create from generated content (the agent-pipe pattern):**
```bash
echo '<!doctype html><html>...</html>' | atelier create /path/to/vault notes/idea.html --from-stdin --json
```
Or pass content inline:
```bash
atelier create /path/to/vault notes/idea.html --content "<!doctype html>..." --json
```

**Create from a template (pattern consistency):**
```bash
atelier templates /path/to/vault --json
atelier create /path/to/vault decisions/q3-platform.md --title "Q3 Platform Direction" --template decision-log --json
```

**Self-correct after writing:**
```bash
atelier lint /path/to/vault --json
```
If issues are returned, fix them with subsequent `update` calls. Repeat until `ok: true`.

**Find before edit:**
```bash
atelier search /path/to/vault "performance budget" --in headings,body --limit 5 --json
```
Use the snippet field to confirm the right file before opening it.

**Atomic rename + verify:**
```bash
atelier rename /path/to/vault notes/old-name.html new-name.html --json
atelier link-check /path/to/vault --json
```
Renames don't rewrite incoming links — the `link-check` afterward surfaces any breaks for follow-up.

## Markdown specifics

`.md` and `.markdown` files are first-class in the index alongside HTML. The indexer extracts:

- **Title** — from YAML frontmatter `title:`, then first `<h1>`, then filename
- **Description** — from frontmatter `description:`, then first paragraph
- **Tags** — from frontmatter `tags: [...]` or YAML list
- **Links** — both `[text](path)` and Obsidian-style `[[wikilinks]]`. Wikilinks resolve case-insensitively against any file basename in the vault, regardless of folder.

When updating Markdown via `update --content`, write the full file body including frontmatter — the CLI doesn't merge.

## Path semantics

- Vault path: absolute or relative to cwd
- File paths inside the vault: forward-slash relative paths from vault root (`notes/quick.html`, not absolute)
- Path traversal (`../`) is blocked — vault paths must stay inside the vault root

## When NOT to use

- The user has a single HTML file they want to edit — just use Edit/Write directly
- You need to render Markdown to HTML for one-off display — use the vault's preview server instead, or `markdown-it` directly
- You need to make non-vault changes (settings, etc.)

## Edge case to know

If the user has the file open in the Atelier desktop app with unsaved edits, and you write to that file via CLI, the GUI's editor still holds the unsaved buffer. Saving in the GUI will overwrite your CLI write. Tell the user to save (or close) the file in the GUI before you operate on it.

## Reference

Run `atelier --help` for the full command list. Project: https://atelier.codependentai.io · npm: https://www.npmjs.com/package/@codependentai/atelier