CLI Reference

Scritorio includes a Bun-powered CLI for agents, scripts, and developers. From the repository root, run it with:

bun run scritorio <command>

The package binary is named scritorio, and the implementation lives in packages/cli/src/main.ts.

Output Rules

Most commands support --json. In JSON mode, structured data is printed to stdout. Human output is printed to stdout when --json is not present. The ai tool-smoke command prints progress logs to stderr and the final model answer to stdout. Paths accept absolute paths, repo-relative paths, ~, and ~/....

Global Options

Option	Applies to	Description
`--json`	Most commands	Print structured JSON.
`--project <path>`	Project, book, Codex, and AI commands	Select the book, series, or destination project path.

`doctor`

Checks that the local CLI environment can see the schema migration, sample project, and Bun runtime.

bun run scritorio doctor
bun run scritorio doctor --json

Returns a status for:

schema
sample-project
bun

The exit code is 0 when all checks pass and 1 when any check fails.

`project inspect`

Indexes a local project and reports its shape.

bun run scritorio project inspect --project examples/the-long-silence
bun run scritorio project inspect --project examples/the-long-silence --json

This command rebuilds .scritorio/index.sqlite from Markdown files. It ignores .git, .scritorio, and node_modules. It records file metadata, front matter, manuscript units, beat-sheet links, Codex entries, full-text search rows, and Codex mentions. The result includes:

resolved project path
index database path
detected project kind
Markdown file count
indexed file count
front matter block count
sample indexed files

`index rebuild`

Rebuilds the local index for a project. It currently returns the same inspection result as project inspect.

bun run scritorio index rebuild --project examples/the-long-silence
bun run scritorio index rebuild --project examples/the-long-silence --json

Use this after direct filesystem edits or before validating index-derived behavior.

`book create`

Creates a standalone book project.

bun run scritorio book create \
  --title "My Book" \
  --type fiction \
  --project ~/Books/my-book \
  --genre "Hard Science Fiction" \
  --point-of-view third_person \
  --structure novel

Options:

Option	Required	Values	Description
`--title <title>`	Yes	any text	Book title.
`--project <path>`	Yes	path	Destination folder.
`--type <type>`	No	`fiction`, `nonfiction`	Defaults to `fiction`.
`--genre <genre>`	No	any text	Stored in `book.md`.
`--point-of-view <pov>`	No	`first_person`, `second_person`, `third_person`	Defaults to `third_person`.
`--pov <pov>`	No	same as `--point-of-view`	Alias for `--point-of-view`.
`--structure <structure>`	No	`blank`, `novel`, `nonfiction`	Defaults to `blank`.
`--json`	No	flag	Print structured result.

The command creates:

book.md
story.yml
.scritorio/settings.json
manuscript/
Codex folders for characters, locations, organizations, items, concepts, events, and style
starter style files at codex/style/series-style-guide.md and codex/style/dialogue-rules.md

It refuses to overwrite an existing book.md.

`series create`

Creates a series workspace.

bun run scritorio series create \
  --title "My Series" \
  --project ~/Books/my-series \
  --series-type mixed

Options:

Option	Required	Values	Description
`--title <title>`	Yes	any text	Series title.
`--project <path>`	Yes	path	Destination folder.
`--series-type <type>`	No	`fiction`, `nonfiction`, `mixed`	Defaults to `mixed`.
`--json`	No	flag	Print structured result.

The command creates:

series.md
story.yml
.scritorio/settings.json
books/
Codex folders for characters, locations, organizations, items, concepts, events, and style
starter style files at codex/style/series-style-guide.md and codex/style/dialogue-rules.md

It refuses to overwrite an existing series.md.

`book move`

Moves a book project into a series workspace or back out to the default Scritorio books folder.

bun run scritorio book move --project ~/Books/my-book --series ~/Books/my-series
bun run scritorio book move --project ~/Books/my-series/books/my-book --out

Options:

Option	Required	Description
`--project <book-path>`	Yes	Existing book project containing `book.md`.
`--series <series-path>`	Required unless `--out` is used	Existing series project containing `series.md`.
`--out`	Required unless `--series` is used	Move the book to `~/Documents/Scritorio`.
`--json`	No	Print structured result.

When moving into a series, the destination is <series>/books/. If a folder with the same name exists, Scritorio chooses a numbered unique path.

`codex create`

Creates a new Codex entry Markdown file.

bun run scritorio codex create \
  --project ~/Books/my-book \
  --entry-type character \
  --name "Mara Vale" \
  --aliases "Mara,Captain Vale" \
  --short-description "A cautious explorer with an old debt." \
  --categories "cast,expedition" \
  --tags "viewpoint,arc" \
  --no-global

Options:

Option	Required	Description
`--project <path>`	Yes	Existing project folder.
`--entry-type <type>`	No	Codex type. Alias: `--codex-type`. Defaults to `concept`.
`--name <name>`	Yes	Entry name and filename seed.
`--aliases <a,b>`	No	Comma-separated aliases.
`--short-description <text>`	No	Compact description for search and AI context.
`--categories <a,b>`	No	Comma-separated categories.
`--tags <a,b>`	No	Comma-separated tags.
`--global`	No	Mark entry global.
`--no-global`	No	Mark entry local to the project.
`--json`	No	Print structured result.

Supported Codex types:

Canonical type	Accepted aliases
`characters`	`character`
`locations`	`location`, `place`, `places`
`organizations`	`organization`
`items`	`item`, `object`, `objects`
`concepts`	`concept`, `term`, `terms`
`events`	`event`, `timeline`, `timeline-event`
`style`	`style`

The command writes to codex/<type>/<safe-name>.md. If the preferred filename already exists, it appends a numeric suffix.

`codex list`

Lists compact Codex entries.

bun run scritorio codex list --project examples/the-long-silence
bun run scritorio codex list --project examples/the-long-silence --entry-type character --json

Options:

Option	Required	Description
`--project <path>`	Yes	Existing project folder.
`--entry-type <type>`	No	Optional Codex type filter. Alias: `--codex-type`.
`--json`	No	Print structured result.

The command reads Markdown directly from disk. Compilation files ending in -compilation.md or -compilation.mdx are ignored.

`codex get`

Looks up one Codex entry by name, alias, title, filename stem, or partial-name match.

bun run scritorio codex get \
  --project examples/the-long-silence \
  --entry-type character \
  --name "Adrian Huxon" \
  --json

Options:

Option	Required	Description
`--project <path>`	Yes	Existing project folder.
`--entry-type <type>`	No	Codex type. Alias: `--codex-type`. Defaults to `concept`.
`--name <name>`	Yes	Name, alias, title, filename stem, or partial name.
`--json`	No	Print structured result.

The result includes project path, relative path, semantic type, name, title, aliases, summary, and source excerpt.

`codex search`

Searches Codex entries with simple local scoring.

bun run scritorio codex search \
  --project examples/the-long-silence \
  --query "post scarcity" \
  --json

Options:

Option	Required	Description
`--project <path>`	Yes	Existing project folder.
`--query <query>`	Yes	Search query.
`--entry-type <type>`	No	Optional Codex type filter. Alias: `--codex-type`.
`--json`	No	Print structured result.

The command scores candidate name, title, type, path, summary, and source excerpt. It returns up to eight matches.

`codex propose-update`

Creates a review-only proposal for a character dossier update. It never writes files.

bun run scritorio codex propose-update \
  --project examples/the-long-silence \
  --entry-type character \
  --name "Adrian Huxon" \
  --change-summary "Clarify that Adrian lives in Vespera on Chiron." \
  --target-section "Residence" \
  --proposed-markdown "## Residence\n\nAdrian lives in Vespera on Chiron." \
  --json

Options:

Option	Required	Description
`--project <path>`	Yes	Existing project folder.
`--entry-type character`	Recommended	Accepted for consistency, but the command currently always resolves character entries.
`--name <name>`	Yes	Character name, alias, title, filename stem, or partial name.
`--change-summary <text>`	Yes	Natural-language summary of the requested canon change.
`--target-section <heading>`	No	Markdown heading to inspect or replace.
`--proposed-markdown <markdown>`	No	Proposed replacement or insertion text.
`--json`	No	Print structured result.

The result includes the resolved character, original excerpt, proposed Markdown, applied: false, and warnings. Narrative-role changes are narrowed to a single Role field proposal when the requested role matches one of Scritorio’s known narrative roles.

`ai tool-smoke`

Runs a real OpenAI Responses API tool-calling smoke test against a selected project.

OPENAI_API_KEY=sk-... bun run scritorio ai tool-smoke \
  --project examples/the-long-silence \
  --persona character-psychologist \
  --ask "What should I remember about Adrian?" \
  --model gpt-5.5

Options:

Option	Required	Description
`--project <path>`	Yes	Existing project folder.
`--persona <persona-id>`	No	Chat persona. Defaults to `developmental-editor` when omitted or invalid.
`--ask <question>`	Yes	User question. Alias: `--prompt`.
`--model <model>`	No	OpenAI model. Defaults to `gpt-5.5`.

Supported persona ids:

developmental-editor
character-psychologist
continuity-editor
worldbuilding-auditor
first-time-reader
writing-coach

The smoke test registers the canon-only tool subset described in Tool Calling, requires the model to call a local canon tool before answering on the first round, executes up to four tool rounds, and prints the final assistant answer. It does not currently register the desktop advisor get_manuscript_context tool. The smoke-test tool set includes generic review-only Codex mutation tools:

propose_codex_update for changing existing characters, locations, organizations, items, concepts, events, and style entries
propose_codex_create for proposing new Codex entries, including optional character soul.md files
propose_character_update for legacy character-update behavior

These tools do not write files during the smoke test. They return proposal payloads that a desktop review/apply flow can handle.

Exit Codes

Current behavior:

0 for successful commands
1 for command failures or thrown validation/provider errors
2 for unknown commands

The doctor command also uses 1 when an environment check fails.

Command Inventory

scritorio doctor [--json]
scritorio project inspect --project <path> [--json]
scritorio index rebuild --project <path> [--json]
scritorio book create --title <title> --type fiction|nonfiction --project <path> [--genre <genre>] [--point-of-view first_person|second_person|third_person] [--structure blank|novel|nonfiction] [--json]
scritorio book move --project <book-path> --series <series-path> [--json]
scritorio book move --project <book-path> --out [--json]
scritorio series create --title <title> --project <path> [--series-type fiction|nonfiction|mixed] [--json]
scritorio codex create --project <path> --entry-type <type> --name <name> [--aliases a,b] [--short-description text] [--categories a,b] [--tags a,b] [--global|--no-global] [--json]
scritorio codex list --project <path> [--entry-type <type>] [--json]
scritorio codex get --project <path> --entry-type <type> --name <name> [--json]
scritorio codex search --project <path> --query <query> [--entry-type <type>] [--json]
scritorio codex propose-update --project <path> --entry-type character --name <name> --change-summary <text> [--target-section <heading>] [--proposed-markdown <markdown>] [--json]
scritorio ai tool-smoke --project <path> --persona <persona-id> --ask <question> [--model gpt-5.5]

Scritorio

​CLI Reference

​Output Rules

​Global Options

​doctor

​project inspect

​index rebuild

​book create

​series create

​book move

​codex create

​codex list

​codex get

​codex search

​codex propose-update

​ai tool-smoke

​Exit Codes

​Command Inventory

CLI Reference

Output Rules

Global Options

`doctor`

`project inspect`

`index rebuild`

`book create`

`series create`

`book move`

`codex create`

`codex list`

`codex get`

`codex search`

`codex propose-update`

`ai tool-smoke`

Exit Codes

Command Inventory