# Commands

`check`, `extract`, `build`, and `serve` use `./diplodocus.yaml` unless given `--config PATH`. Extraction writes `.diplodocus/documentation.sqlite` beside that configuration; `extract --output PATH` changes the snapshot destination. `generate` requires `--input PATH`. `generate`, `build`, and `serve` write to `./site` unless given `--output PATH`. Relative command-line paths resolve from the working directory. 

For example, extract once and generate from the completed snapshot: 

```console
diplodocus extract --output documentation.sqlite
diplodocus generate --input documentation.sqlite --output site
```

The snapshot includes structured documentation, provenance, and local assets. Generation validates its records and output before publication. A copied snapshot can be generated without the original source files or language runtimes. See [portable snapshots](<../guide/snapshots>) for compatibility and refresh behavior. 

Use `extract --watch` to prepare snapshots continuously for another frontend. It extracts once, then watches declared sources, configuration, and referenced assets, including sibling package checkouts. Saves are debounced, and extractions run one at a time. Each successful publication writes and flushes one JSON line to stdout: 

```json
{"format_version":1,"event":"snapshot","path":"/absolute/path/documentation.sqlite"}
```

Diagnostics go to stderr. An initial failure exits without emitting an event. Later failures retain the previous snapshot and keep watching for corrections. Consumers should use publication events rather than observing temporary database files. If a consumer needs several passes over a snapshot, copy it before processing so a subsequent publication cannot change its input between passes. Stopping the watcher waits for active example execution to clean up. The [VitePress example](<https://github.com/jolars/diplodocus/tree/main/examples/vitepress>) connects these events to an existing frontend's development server. 

`serve` listens on `127.0.0.1:8000` by default. Use `--host` and `--port` to change the address, and `--live-reload` to refresh open pages after a successful rebuild. A failed rebuild prints diagnostics and keeps serving the last successful site. Warnings permit a successful exit; errors cause a nonzero exit status. Output destinations cannot replace declared inputs. The [diagnostics guide](<../guide/diagnostics>) explains reported codes and failed builds. 

Start with the [small example](<../guide/quick-start>) or see its [workspace configuration](<../guide/configuration>). 

**Usage:** `diplodocus <COMMAND>` 

<a id="diplodocus-build"></a>

## `diplodocus build`

Build a static documentation site 

**Usage:** `diplodocus build [OPTIONS]` 

<a id="options"></a>

### Options

- `--config <PATH>` 
  
      Path to the workspace configuration file 
  
      Default value: `./diplodocus.yaml`
- `--output <PATH>` 
  
      Directory in which to write the generated site 
  
      Default value: `./site`

<a id="diplodocus-check"></a>

## `diplodocus check`

Check documentation without writing a site 

**Usage:** `diplodocus check [OPTIONS]` 

<a id="options-2"></a>

### Options

- `--config <PATH>` 
  
      Path to the workspace configuration file 
  
      Default value: `./diplodocus.yaml`

<a id="diplodocus-extract"></a>

## `diplodocus extract`

Extract a portable SQLite documentation snapshot 

**Usage:** `diplodocus extract [OPTIONS]` 

<a id="options-3"></a>

### Options

- `--config <PATH>` 
  
      Path to the workspace configuration file 
  
      Default value: `./diplodocus.yaml`
- `--output <PATH>` 
  
      Snapshot destination (defaults to .diplodocus/documentation.sqlite beside the configuration)
- `--watch` 
  
      Re-extract changed inputs and emit a JSON line after each published snapshot

<a id="diplodocus-generate"></a>

## `diplodocus generate`

Generate a site using only a completed snapshot 

**Usage:** `diplodocus generate [OPTIONS] --input <PATH>` 

<a id="options-4"></a>

### Options

- `--allow-components` 
  
      Emit executable browser bundles retained in this trusted snapshot
- `--input <PATH>` 
  
      Completed SQLite documentation snapshot
- `--output <PATH>` 
  
      Directory in which to write the generated site 
  
      Default value: `./site`
- `--format <FORMAT>` 
  
      Output complete site pages or embeddable HTML and Markdown fragments 
  
      Default value: `site` 
  
      Possible values: `site`, `fragments`
- `--url-map <PATH>` 
  
      Public document and asset URL map (requires --format fragments)

<a id="diplodocus-serve"></a>

## `diplodocus serve`

Build and serve a site, rebuilding when declared inputs change 

**Usage:** `diplodocus serve [OPTIONS]` 

<a id="options-5"></a>

### Options

- `--config <PATH>` 
  
      Path to the workspace configuration file 
  
      Default value: `./diplodocus.yaml`
- `--output <PATH>` 
  
      Directory in which to write the generated site 
  
      Default value: `./site`
- `--host <ADDRESS>` 
  
      Address on which to serve the generated site 
  
      Default value: `127.0.0.1`
- `--port <PORT>` 
  
      Port on which to serve the generated site 
  
      Default value: `8000`
- `--live-reload` 
  
      Refresh open browser pages after successful rebuilds