CLI

The graft CLI is intended for local development, scripting, demos, and manual repository operations. It should stay thin: parse arguments, execute the matching repository pragma through the embedded SQLite VFS, and print output.

Global Options

graft --db path/to/app.db status

If --db is omitted, the CLI uses app.db in the discovered repository worktree or in the current directory.

SQL Runner

graft sql "SELECT 1;"
graft sql "CREATE TABLE t(id INTEGER PRIMARY KEY); INSERT INTO t DEFAULT VALUES;"
cat script.sql | graft sql

graft sql opens the database through the embedded Graft VFS. This is the easiest way to test Graft locally without loading the SQLite extension manually.

It requires an existing .graft/ repository unless the SQL batch includes:

PRAGMA graft_init;

Repository Commands

Command	Purpose
graft init	Create .graft/ next to the database path.
graft clone <remote> [branch]	Clone a remote repository into a worktree database path.
graft status	Show branch, HEAD, staged, unstaged, and conflict state.
graft add [path]	Stage the current database or a repo-relative SQLite database path.
graft rm [path]	Stage removal of a tracked database path.
graft commit -m <message>	Create a repository commit from the index.
graft log	Show repository history.
graft show [--json] <rev>	Show one repository commit.
graft diff [--json] [--rows] [--staged] [from] [to] [path]	Compare worktree, index, or revisions.
graft checkout [-f] <rev> [path]	Check out a revision or restore one path from a revision.
graft restore [--staged] [--source rev] <path>	Restore a worktree or staged path.
graft export [--source rev] --output <file> [path]	Write a Graft database snapshot as a physical SQLite file.
graft reset [--soft|--mixed|--hard] <rev>	Move the current branch or HEAD.

graft diff --rows expands modified SQLite database snapshots into table and row changes:

graft diff --rows HEAD~1 HEAD app.db
graft diff --rows --staged app.db
graft diff --json --rows HEAD~1 HEAD app.db

Exporting Physical SQLite Files

graft export --output app.inspect.db app.db
graft export --source HEAD --output app.head.db app.db
graft export --source HEAD~1 --output app.previous.db app.db

Without --source, graft export writes the current worktree Volume. With --source, it writes the database snapshot stored in that revision. The output is a normal SQLite database that can be opened by standard tools.

Exported files are not automatically synchronized back into Graft. If you edit one with ordinary SQLite tooling and want to import it, stage the physical file explicitly:

graft --db .graft-control.db add app.db

Branches And Tags

Command	Purpose
graft branch	List local branches.
graft branch -r	List remote-tracking branches.
graft branch -a	List local and remote-tracking branches.
graft branch <name> [start-point]	Create a branch.
graft branch -d <name>	Delete a fully merged branch.
graft branch -D <name>	Force-delete a branch.
graft branch -m [old] <new>	Rename a branch.
graft branch -u <remote>/<branch> [branch]	Set upstream.
graft branch --unset-upstream [branch]	Remove upstream config.
graft switch <branch>	Switch branches.
graft switch -c <branch> [start-point]	Create and switch.
graft tag	List tags.
graft tag <name> [rev]	Create a lightweight tag.
graft tag -a <name> [-m message] [rev]	Create an annotated tag.
graft tag -d <name>	Delete a tag.

Remotes

Command	Purpose
graft remote add <name> <uri>	Add a remote.
graft remote list	List remotes.
graft remote get-url <name>	Print a remote URL.
graft remote set-url <name> <uri>	Update a remote URL.
graft remote rename <old> <new>	Rename a remote.
graft remote remove <name>	Remove a remote.
graft remote prune <name>	Delete stale remote-tracking refs.
graft ls-remote <remote>	List refs advertised by a remote.
graft fetch [--all] [remote] [branch]	Fetch remote branches.
graft pull [remote] [branch]	Fast-forward or enter merge state.
graft push [--all] [--force] [remote] [branch]	Push local refs.

Merge And Conflict Commands

graft merge <rev>
graft merge --abort
graft merge --continue -m "merge message"
graft conflicts
graft resolve --ours app.db
graft resolve --theirs app.db

Conflicts are stored in the index as staged conflict entries. For the currently opened SQLite database, non-conflicting row changes can be auto-merged and staged directly; same-row, schema, add/delete, and opaque-table conflicts still require resolution. After resolving, commit with graft merge --continue.