​
Agent And CLI Interface

Scritorio should be deeply usable by agents. The desktop UI is important, but agents need a stable command surface that can inspect projects, run workflows, and produce machine-readable results without clicking through the app.

​
Product Principle

Anything meaningful that can be done in the app should eventually be possible through the CLI. The CLI should be installed as part of Scritorio and should work against the same local project folders, indexes, settings, reports, and provider configuration as the desktop app.

​
Why This Matters

Agent usability is not only developer convenience. It lets authors ask an agent to:
  • audit a chapter
  • find contradictions
  • create a report
  • prepare an index draft
  • summarize source coverage
  • run a blind reader reaction
  • generate a visual prompt
  • compare revisions
  • inspect project health
The author still controls what context is sent to AI providers. Agents should help operate Scritorio, not bypass its privacy model.

​
CLI Design Goals

The CLI should be:
  • complete enough to mirror app workflows
  • scriptable and predictable
  • safe by default
  • explicit about file changes
  • explicit about AI context
  • friendly to both humans and tool-calling agents
  • able to return structured output

​
Output Conventions

Commands should support human-readable output and machine-readable output. Expected conventions:
  • --json returns structured JSON on stdout
  • logs, progress, and warnings go to stderr
  • commands that change files explain what they wrote
  • dry-run or preview modes are available for destructive or AI-sending actions
  • nonzero exit codes distinguish validation errors, provider errors, missing project state, and command misuse

​
Initial Command Areas

The first CLI surface should cover:
  • project detection and validation
  • file tree and metadata inspection
  • search
  • index rebuild
  • context preview
  • editorial review
  • reader persona review
  • writing coach exercises
  • visual prompt generation
  • report creation and listing
Future command areas should cover:
  • bibliography and citation checks
  • index term extraction
  • Git snapshot and comparison workflows
  • asset management
  • project migrations

​
Privacy And AI Calls

CLI workflows must follow the same privacy rules as the app:
  • no background uploads
  • explicit AI action
  • context preview before provider calls
  • ability to exclude files or passages
  • local report output
  • local settings and credentials
Agents should be able to request a preview first, then run the final command only after user approval when the workflow sends content to an external provider.

​
Shared Core

The CLI and desktop app should share core project logic. File parsing, indexing, context assembly, provider calls, report writing, and validation should not be reimplemented separately for UI and CLI. This keeps behavior consistent and prevents the command-line version from becoming a brittle automation layer around the app.

​
Current Implementation Docs

The live docs for the current implementation are split into:
  • Tool Calling, which explains the OpenAI chat tool flow, persona prompt formation, local canon tools, and review-only canon proposals.
  • CLI Reference, which documents every command currently supported by packages/cli/src/main.ts.