Skip to content

CLI And Output Contract

Assertions

CLI-001 - JSON output is deterministic and isolated from diagnostics

Contract: Every command accepting --json MUST emit one valid, key-sorted, ANSI-free JSON document on stdout. Logs and diagnostics MUST remain on stderr. The envelope MUST contain schema_version, command, success, exit_code, code, tool_version, and workspace.

Evidence:

CLI-002 - Exit codes and capabilities remain stable

Contract: Exit codes MUST retain these meanings: 0 success, 1 differences or pending work, 2 unresolved conflicts, 3 invalid workspace or managed file, 4 API or authentication failure, 5 concurrent change or workspace lock, 6 partial operation or required recovery, 7 unsafe operation blocked, 8 newer stable release available, and 9 internal failure. capabilities --json MUST advertise the exact public command, feature, schema, and exit-code surface.

Evidence:

CLI-003 - Connection and token precedence is deterministic

Contract: Joplin connection resolution MUST apply CLI options before environment variables, workspace configuration, the loopback default, and loopback discovery. Token-file input MUST override JOPLIN_TOKEN; raw token values MUST NOT be accepted as CLI arguments except that the local-only mcp stdio transport MUST require --token. Its Joplin --port MUST default to 41184 without discovery. Zero or multiple discovered Clipper services MUST fail unambiguously.

Evidence:

CLI-004 - Inspection commands do not mutate state

Contract: status MUST operate from local and base state only. diff MUST NOT mutate local files, workspace state, or Joplin in any output mode; --offline MUST mark remote state unknown rather than implying equality. --exit-code alone MAY convert detected differences to exit 1.

Evidence:

CLI-005 - Workspace initialization is explicit and guarded

Contract: Remote-first initialization MUST reject an existing unmanaged Markdown collection. Local-first initialization MAY adopt it, but MUST require a successful push dry-run before the first real push. Reinitializing an existing workspace MUST fail rather than replace state.

Evidence:

CLI-006 - Health and update checks are bounded and explicit

Contract: doctor --offline MUST inspect local health without network access. Online authentication failures MUST be distinguished from local workspace failures. update-check MUST use stable Releases by default, MUST never self-update, and MUST distinguish current, outdated, offline-skipped, and network-failure outcomes.

Evidence:

CLI-007 - Note and resource helpers preserve managed content

Contract: Note metadata helpers MUST rewrite atomically and validate the managed header. Resource pull MUST download referenced resources only into workspace internal storage and MUST NOT rewrite :/resource-id or :/note-id links.

Evidence: