# Subo

> Subo (素帛) is a local LaTeX writing desk for macOS. The 100 MB installer bundles a trimmed TeX Live (pdfLaTeX and XeLaTeX), Chinese typesetting works out of the box, and missing packages are fetched at build time. Builds run on the user's machine, offline if needed. The `subo` command-line tool lets an AI agent build documents to PDF without prompts or dialogs.

Status: early preview, v0.0.2. The macOS installer is waiting on signing and notarization, so public downloads are not open yet. Linux can be built from source. Windows is not available.

This file is written for AI agents working on a user's behalf. The human-facing page is https://www.subo.ink/ (Simplified Chinese, English and Traditional Chinese).

## Building a document with the subo CLI

The CLI never prompts and never opens a window. Add `--json` to any command to get one flat JSON object on stdout instead of human-readable text. Human-readable output is currently in Chinese; JSON field names are always English.

Build a project folder, installing any missing packages, and report as JSON:

```
subo build ./paper --install --json
```

A successful build:

```json
{
  "ok": true,
  "entry": "main.tex",
  "engine": "xelatex",
  "ms": 3539,
  "pdf": "/Users/you/paper/main.pdf",
  "errors": [],
  "missing": [],
  "installed": ["pgfplots"],
  "warnings": [],
  "next": []
}
```

- `ok`: whether the PDF was produced.
- `entry`: the main `.tex` file that was compiled.
- `engine`: the TeX engine used.
- `ms`: build time in milliseconds.
- `pdf`: absolute path of the output PDF.
- `errors`: compile errors. Fix these in the source.
- `missing`: packages the document needs that are not installed.
- `installed`: packages fetched during this build.
- `warnings`: non-fatal warnings.
- `next`: commands to run next when the build did not succeed.

## Exit codes

Every command's exit code says what to do next:

- `0`: success. The PDF path is in `pdf`.
- `1`: the document did not build. Follow `errors` and `next`.
- `2`: the command was used wrongly. Read `hint` and fix the command.
- `3`: environment problem. Run `subo doctor` first.

## Everyday commands

- `subo doctor`: check the environment.
- `subo inspect`: show the entry file and engine of a project.
- `subo new`: create a project from a built-in template.
- `subo install`: install packages or engines.
- `subo build`: compile a project to PDF.

## Projects and templates

A project is a plain folder on disk: sources, images and bibliography are ordinary files. There is no account and no proprietary format. Intermediate files and logs are kept in Subo's own directory, so the project folder only gains the PDF.

Built-in templates, all written for XeLaTeX with Chinese working out of the box: `thesis-zh` (thesis), `article-zh` (Chinese article), `article-zh-tw` (Traditional Chinese article), `paper-en` (English paper), `report-zh` (report), `slides-zh` (slides), `poster` (academic poster), `resume-zh` (Chinese résumé), `resume-en` (English résumé).

Subo can also open an existing folder in place, or import an Overleaf zip export, an arXiv source tar.gz, or a GitHub zip download.

## TeX environment

- Starts with pdfLaTeX and XeLaTeX. LuaLaTeX, pLaTeX, other packages and fonts are fetched on demand.
- Package sources (CTAN mirrors such as Tsinghua TUNA and USTC, or a custom URL) can be speed-tested and chosen in Settings.
- Offline, missing packages are queued and fetched once the machine is back online.
- If a full TeX Live is already installed, Subo uses it first.

## AI inside the app

AI is off by default and the app makes no background requests. When the user configures a model (any OpenAI-compatible service, or a local server such as Ollama, LM Studio or vLLM), AI suggestions appear only next to build errors and at the cursor (⌘K). Each suggestion is an inline change that is test-compiled on the local machine before the user accepts it.

## Links

- [Website](https://www.subo.ink/)
- [Sample project (English)](https://www.subo.ink/assets/sample-en.zip): the built-in `paper-en` template
- [Product film (English)](https://www.subo.ink/assets/subo-en.mp4)