# How to Deliver Archify Diagrams with a Specific Output Path

> Learn how to deliver Archify diagrams to a specific output path using CLI flags or helper scripts. Customize your diagram deployment effortlessly.

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

---

**You can deliver Archify diagrams to a custom location by using the `--output` flag in the CLI or by passing a path argument to helper scripts like `scripts/build-start.mjs` and `scripts/build-guide.mjs`.**

Archify, an open-source diagramming tool from the `tt-a1i/archify` repository, provides flexible options for controlling where generated files land. Whether you are integrating diagrams into a documentation pipeline or organizing outputs into structured directories, understanding the output path resolution is essential for reproducible builds.

## Using the CLI --output Flag

The primary interface for specifying a destination is the `archify render` command. This command accepts a `--output` (or `-o`) parameter that overrides the default behavior of placing files beside the source.

The syntax follows this pattern:

```bash
archify render <type> <input-file> --output <target-path>

```

- **`<type>`** — The diagram format, such as `workflow`, `architecture`, or `mermaid`.
- **`<input-file>`** — The source file in JSON, YAML, or Mermaid format.
- **`<target-path>`** — An absolute or relative path where the final HTML (or other supported format) will be written.

If you omit the `--output` flag, Archify defaults to creating the output file next to the source with a `.html` extension.

### Example: Rendering to a Custom Directory

```bash

# Render a workflow diagram to the docs folder

archify render workflow examples/workflow.json \
    --output ./docs/diagrams/workflow.html

```

## Working with Build Scripts

For specialized generation tasks, the repository includes convenience scripts that accept output paths as positional arguments. These scripts wrap the core rendering logic while ensuring static assets are co-located with the generated HTML via the `copySiteAssets` function.

### Build Start Script

The `scripts/build-start.mjs` script generates the **Start** page and accepts an optional output path:

```bash
node scripts/build-start.mjs ./public/start-page.html

```

### Build Guide Script

Similarly, `scripts/build-guide.mjs` handles the **Guide** page generation:

```bash
node scripts/build-guide.mjs ./public/guide.html

```

Both utilities internally resolve paths and create necessary directories before writing files.

## Understanding the Output Path Resolution

Behind the scenes, Archify centralizes path logic in `archify/renderers/shared/output-path.mjs`. This module handles directory creation, path normalization, and safety checks to ensure reliable file delivery regardless of whether you are running an installed skill or a local development build.

### The output-path.mjs Helper

The `output-path.mjs` module exposes utilities that resolve the final file name and ensure parent directories exist before writing. This prevents errors when targeting nested output locations that have not yet been created.

The test suite in `archify/test/output-path.test.mjs` validates these behaviors, confirming that the module correctly handles:
- Relative path resolution from the current working directory.
- Absolute path preservation.
- Directory creation for missing parent folders.

## Step-by-Step Workflow Example

Follow this pattern to deliver diagrams with precise control over their destination:

1. **Prepare your source file** (e.g., [`my-workflow.json`](https://github.com/tt-a1i/archify/blob/main/my-workflow.json) describing your diagram).

2. **Run the render command** with an explicit output location:

   ```bash
   archify render workflow my-workflow.json --output ./output/diagram.html
   ```

3. **Verify asset co-location** — The generated HTML appears at the specified path, and `copySiteAssets` ensures static dependencies reside alongside it.

## Summary

- Use the **`--output`** flag with `archify render` to specify a custom destination for any diagram type.
- Leverage **`scripts/build-start.mjs`** and **`scripts/build-guide.mjs`** for page-specific generation with positional path arguments.
- The **`output-path.mjs`** module in `archify/renderers/shared/` handles directory creation and path normalization automatically.
- When omitted, outputs default to the source file's directory with a `.html` extension.

## Frequently Asked Questions

### How do I specify a custom output directory for Archify diagrams?

Use the `--output` flag followed by your desired path. For example: `archify render workflow input.json --output ./docs/output.html`. The `output-path.mjs` helper will create the directory structure if it does not exist.

### What happens if I don't provide an output path?

Archify writes the generated file beside the source file using the same base name but with a `.html` extension. This default behavior ensures you can quickly generate previews without specifying additional parameters.

### Can I use relative paths for the output?

Yes. The `output-path.mjs` module resolves relative paths against the current working directory. Both relative paths like [`./docs/diagram.html`](https://github.com/tt-a1i/archify/blob/main/./docs/diagram.html) and absolute paths like [`/home/user/project/docs/diagram.html`](https://github.com/tt-a1i/archify/blob/main//home/user/project/docs/diagram.html) are supported.

### How are static assets handled when using a custom output path?

Helper scripts such as `build-start.mjs` and `build-guide.mjs` invoke `copySiteAssets` to ensure that CSS, JavaScript, and other static dependencies are copied to the same directory as the generated HTML, maintaining proper relative links regardless of the output location.