Generated from spec/*.md

CLI surface

This document describes the intended command-line interface at the project level.

Core commands

Set a value

git meta set [-t <type>] <target> <key> <value>

If -t is not given, the value type defaults to string.

Examples:

git meta set commit:314e7f0fa7 agent:model claude-4.6
git meta set -t list branch:sc-branch-1-deadbeef agent:chat '["hello", "world"]'
git meta set -t set path:src/metrics owners '["schacon", "caleb"]'

Get values

git meta get <target> [<key>]

Behavior:

  • with only <target>, show all keys for the target
  • with <target> <key>, show the exact key if present
  • with <target> <partial-key>, show matching subkeys

Remove a key

git meta rm <target> <key>

This removes the logical key and records a whole-key tombstone.

List operations

git meta list:push <target> <key> <value>
git meta list:pop <target> <key> <value>

Notes:

  • list:push appends a new list entry
  • list:pop requires explicit exchange semantics before implementation is finalized; see Lists
  • if a string key is pushed to as a list, the implementation may convert it to a list

Set operations

git meta set:add <target> <key> <value>
git meta set:rm <target> <key> <value>

Notes:

  • set:add creates the set if it does not already exist
  • set:add is idempotent for an existing member
  • set:rm removes a single member and records a member tombstone

Exchange commands

Serialize

git meta serialize

Writes a new metadata commit for the current local shareable state.

Materialize

git meta materialize [<remote>]

Behavior:

  • if <remote> is given, materialize from that remote metadata ref
  • if omitted, inspect all known metadata remotes and materialize them

Dry-run materialize

git meta materialize --dry-run [<remote>]

Useful for reporting the merge strategy and conflict decisions without applying them.

Target syntax

Targets use the syntax documented in Targets and keys.

Examples:

commit:<sha>
change-id:<uuid>
branch:<name-or-uuid>
path:src/metrics
project

Value encoding

String input

Without -t, <value> is interpreted as a string.

List input

For -t list, <value> should be a JSON array of strings.

Set input

For -t set, <value> should be a JSON array of unique strings.

Output modes

git meta get may support:

  • human-readable tabular output
  • --json
  • --with-authorship for author/timestamp metadata in JSON mode

The output model is documented in Output.