# CLI

shikiphp 附带一个小型命令行工具，位于 `bin/shikiphp`（在项目中安装为
`vendor/bin/shikiphp`）。它有三个命令：`highlight`
将单个文件渲染为 HTML，而 `langs` 和 `themes` 会列出捆绑内容。

## `highlight`

高亮文件并将结果输出到 HTML，写入标准输出。

```bash
vendor/bin/shikiphp highlight <file> [--lang=<lang>] [--theme=<theme>]
```

- `<file>` — 要读取的路径。必须是现有文件；不会读取标准输入。
- `--lang` — 语言 id 或别名。若省略，则按原样将文件扩展名用作 id（若没有扩展名，则回退到 `txt`）。
- `--theme` — 主题 id。默认为 `github-dark`。

```bash
vendor/bin/shikiphp highlight src/App.php --lang=php --theme=nord
```

输出与 [`codeToHtml`](https://shikiphp.inline0.dev/zh/docs/api#shikiphpcodetohtml) 返回的单主题
`<pre class="shiki …">` 代码块相同，末尾带一个换行符，因此可以直接重定向到文件：

```bash
vendor/bin/shikiphp highlight src/App.php --theme=github-light > app.html
```

该命令不接受其他选项。对于双主题、转换器或任何其他[选项](https://shikiphp.inline0.dev/zh/docs/options)，请改用 PHP API。

### 选项和参数

选项必须采用 `--name=value` 格式。任何其他以 `--` 开头的参数都会被忽略，而最后一个不以 `--` 开头的参数会被视为文件。因此，`--lang php file.rs` 会将 `file.rs` 作为 Rust 高亮：`--lang` 会被忽略，`php` 会被 `file.rs` 替换，语言则根据 `.rs` 扩展名确定。

### 语言推断

如果没有 `--lang`，扩展名会原样成为语言 id。若扩展名本身是捆绑的 id 或别名（例如 `php`、`js`、`ts`、`tsx`、`py`、`rs`、`go`、`md`、`yml`、`json`、`sh` 等），这种方式就可行（参见 [语言](https://shikiphp.inline0.dev/zh/docs/languages)）。以下情况则不适用：

- 没有扩展名的文件，例如 `Makefile` 或 `Dockerfile`，会回退到 `txt`；
- 不是语言 id 的扩展名，例如 `.txt`。

`txt` 不是捆绑语言，因此这两种情况目前都会因 `Unknown language "txt"` 错误而停止（[#3](https://github.com/inline0/shikiphp/issues/3)）。
对于这些文件，请传入 `--lang`：

```bash
vendor/bin/shikiphp highlight Dockerfile --lang=docker
vendor/bin/shikiphp highlight Makefile --lang=make
```

## `langs`

逐行打印捆绑包接受的所有语言 id。

```bash
vendor/bin/shikiphp langs
```

列表共 350 行：先按捆绑顺序列出 253 个捆绑语法 id（非字母顺序），再列出它们的 97 个别名（`js`、`cjs`、`mjs` 等）。
语法 id 中包括 18 个供其他语法嵌入的辅助语法，例如 `vue-directives` 和 `es-tag-css`；名称和别名目录见 [语言](https://shikiphp.inline0.dev/zh/docs/languages)。通过 `sort` 可按字母顺序排列列表。

## `themes`

按字母顺序逐行打印所有捆绑主题 id（共 65 个主题）。

```bash
vendor/bin/shikiphp themes
```

名称和亮色/暗色类型目录见 [主题](https://shikiphp.inline0.dev/zh/docs/themes)。

## 帮助和退出状态

不带命令运行，或使用 `-h` / `--help` / `help`，即可打印用法说明。

```bash
vendor/bin/shikiphp --help
```

| 情况 | 输出 | 退出状态 |
| --- | --- | --- |
| 成功或帮助 | 标准输出 | `0` |
| 未知命令 | 标准错误上的 `Unknown command: <name>` | `1` |
| `highlight` 未提供文件，或文件不存在 | 标准错误上的用法行 | `1` |
| 未知语言或主题 | 未捕获的 `Shikiphp\Exceptions\Highlight`（PHP 致命错误，附带堆栈跟踪） | `255` |