docspec-cli 1.7.1

Command-line interface for DocSpec document conversion
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119

# `docspec-cli`

Command-line interface for DocSpec document conversion.

See the [main DocSpec repository](https://github.com/docspec/docspec) for documentation.

## Usage

```bash
docspec <COMMAND> [OPTIONS]
```

Commands:
- `convert` — Convert documents between formats
- `http` — Run the HTTP API server

### `convert` subcommand

```bash
docspec convert [OPTIONS] [INPUT]
```

#### Arguments

- `INPUT` — Input file (use `-` or omit for stdin)

#### Options

- `-o, --output <FILE>` — Output file (stdout if omitted)
- `-f, --from <FORMAT>` — Input format (auto-detected from extension if omitted). Valid values: `markdown`, `html`, `docx`
- `-t, --to <FORMAT>` — Output format (auto-detected from extension if omitted). Valid values: `blocknote`, `html`, `oxa`, `pandoc-native`
- `--color <WHEN>` — When to use colors: `auto`, `always`, `never` (default: `auto`)
- `-h, --help` — Print help
- `-V, --version` — Print version

### `http` subcommand

```bash
docspec http [OPTIONS]
```

Starts the HTTP API server. Listens on `127.0.0.1:3000` by default.

#### Options

- `--host <HOST>` — Address to bind the server to (default: `127.0.0.1`)
- `--port <PORT>` — Port to listen on. Use `0` for OS-assigned (default: `3000`)
- `-h, --help` — Print help

### Feature flags

`docspec-cli` ships with `http` enabled by default. For a slim install without the HTTP server stack:

```bash
cargo install docspec-cli --no-default-features
```

The resulting binary will only support `docspec convert`; running `docspec http` will print "unknown subcommand".

## Supported Input Formats

- `markdown` — Full Markdown support including headings, lists, tables, and inline formatting
- `html` — HTML input (see note below)
- `docx` — DOCX input (paragraphs and text only)

> **Note:** HTML and DOCX input currently preserve only paragraph text. Other HTML input
> elements and non-paragraph output events (headings, lists, tables, formatting tags, etc.)
> are silently dropped. DOCX input preserves only paragraphs and text; styles, tables, lists,
> images, headers/footers, and tracked changes are silently dropped. For fuller feature
> coverage, use Markdown input with BlockNote JSON output.

## Examples

Convert a Markdown file to BlockNote JSON:

```bash
docspec convert --from markdown --to blocknote input.md --output output.json
```

Convert an HTML file to BlockNote JSON (paragraphs only):

```bash
docspec convert --from html --to blocknote input.html --output output.json
```

Convert a DOCX file to BlockNote JSON (paragraphs only):

```bash
docspec --from docx --to blocknote input.docx --output output.json
```

Convert Markdown from stdin to BlockNote JSON on stdout:

```bash
echo "# Hello" | docspec convert --from markdown --to blocknote
```

Convert Markdown to HTML:

```bash
echo "Hello" | docspec convert --from markdown --to html
```

Convert Markdown to Pandoc native syntax:

```bash
echo "Hello" | docspec convert --from markdown --to pandoc-native
```

Start the HTTP API server on a custom port:

```bash
docspec http --port 8080
```

`--to oxa` selects the [oxa.dev](https://oxa.dev/) JSON writer in place of BlockNote. The `.json`
extension is ambiguous, so `--to oxa` must be explicit. HTML output is selected by `--to html`
or auto-detected from `.html` and `.htm` output paths. Pandoc native output is selected by
`--to pandoc-native` or auto-detected from `.native` output paths.