JSON Output

Most Graft repository commands have a JSON form. Use it for app UIs, automation, tests, and integrations that need structured state.

CLI commands use --json:

graft status --json
graft diff --json --rows HEAD~1 HEAD data.sqlite

The SQLite extension does not expose repository JSON PRAGMAs. Embedded applications should invoke the CLI control plane and decode its JSON response.

Repository Position

Many JSON responses include:

Field	Meaning
`current_head`	Current commit id when available.
`current_branch`	Current branch name when `HEAD` points to a branch.
`operation`	Operation name for mutation responses.

Detached or uninitialized repositories may omit position fields.

Path Entries

Path entries are the primary app-facing unit.

Field	Meaning
`path`	Repository-relative path.
`kind`	`sqlite_database`, `text_file`, or `binary_file`.
`storage`	`sqlite_snapshot`, `inline`, or `external`.
`change`	`added`, `modified`, or `deleted` when available.
`index_status`	Staged status in status output.
`worktree_status`	Unstaged status in status output.
`code`	Git-like two-character status code.
`conflicted`	Whether the path has unresolved conflict stages.

Use kind to choose UI controls. Use storage to decide whether bytes are inline, snapshot-backed, or external-payload-backed.

Status

graft status --json

Important fields:

Field	Meaning
`paths`	One entry per changed path.
`counts`	Counts for staged, unstaged, and conflicted paths.
`has_unstaged_changes`	True when the worktree has unstaged changes.
`has_staged_changes`	True when the index has staged changes.
`has_conflicts`	True when there are unresolved conflicts.
`work_in_progress`	True when any staged, unstaged, conflict, or merge state exists.
`staged_changes`	Lower-level staged changes.
`unstaged_changes`	Lower-level unstaged changes.

Prefer work_in_progress when deciding whether an app can safely switch, pull, or close a review flow.

Diff

graft diff --json
graft diff --json --rows HEAD~1 HEAD data.sqlite

Top-level paths summarizes changed repository paths. SQLite database entries can also include row-level payloads when --rows is present.

Useful database fields include:

Field	Meaning
`row_diff_available`	Whether row diff detail is present.
`logical_status`	Coarse row-diff interpretation.
`capabilities`	SQLite surfaces Graft interpreted.
`limitations`	SQLite surfaces that need caveats.
`tables`	Table-level row changes when available.

Each table entry includes columns, changes, and, for declared-primary-key tables, primary_key_columns. A row change uses rowid for an ordinary rowid table or key for a WITHOUT ROWID table:

{
  "name": "docs",
  "primary_key_columns": ["space_id", "id"],
  "changes": [
    {
      "op": "update",
      "key": { "space_id": "space-1", "id": "doc-1" },
      "old_values": ["space-1", "doc-1", "before"],
      "values": ["space-1", "doc-1", "after"]
    }
  ]
}

Primary-key JSON preserves identity types. BLOB key parts use an explicit marker such as { "$blob": "00ff" }; the same key object can be passed to graft resolve --row.

Conflicts

graft conflicts --json

Conflict output is intended for merge review UIs. It can include path rollups, index stages, row merge analysis, schema conflicts, row conflicts, opaque changes, and blocked reasons.

Common fields:

Field	Meaning
`available`	Whether row-level analysis is available for a database conflict.
`can_auto_merge`	Whether the plan can be applied automatically.
`blocked_reasons`	Why auto-merge is blocked.
`row_conflicts`	Rowid, declared-primary-key, or semantic-key conflicts.
`schema_conflicts`	Schema conflict detail.
`opaque_changes`	Unsupported or opaque SQLite surfaces.
`apply_policy`	SQL apply and validation policy.

File Inventory And Payloads

graft ls-files --json --details
graft payload status --json HEAD
graft payload fetch --json --remote origin HEAD
graft payload prune --json

Use these for file browsers and offline availability panels.

ls-files --details can include object ids, content hashes, and local external payload presence. Payload commands include present, missing, invalid, fetched, candidate, pruned, and byte-count summaries depending on the operation.

Compatibility Guidance

Applications should prefer high-level fields such as paths, kind, storage, current_head, current_branch, work_in_progress, and documented conflict fields. Avoid depending on debug-only fields, storage LSNs, or internal object serialization details.