Commands Detailed command reference for the Libra CLI
This directory contains detailed documentation for all Libra CLI commands. Each document includes a synopsis, option reference, human and structured (JSON) output examples, design rationale, and a parameter comparison with Git and jj.
Every Libra command accepts the following global flags:
Flag Short Description --json-JOutput as JSON (formats: pretty, compact, ndjson) --machineStrict machine mode (implies --json=ndjson --no-pager --color=never --quiet) --no-pagerDisable pager (less) --colorWhen to use colors (auto, never, always) --no-colorDisable colors; equivalent to --color=never --quiet-qSuppress stdout --exit-code-on-warningReturn exit code 9 on warnings --progressControl progress output (json, text, none, auto)
Command Alias Description Doc libra initCreate a new Libra repository with SQLite-backed metadata, vault signing, and optional Git import init.md libra cloneClone a remote repository with vault bootstrapping, shallow clone, and single-branch support clone.md libra configcfgManage repository-local and user-global configuration with vault-backed secret encryption config.md libra completionsGenerate a shell completion script (bash/zsh/fish/powershell/elvish) from the live CLI completions.md
Command Alias Description Doc libra addStage file changes from the working tree into the index add.md libra rmremove, deleteRemove files from the working tree and/or the index rm.md libra mvMove or rename files, directories, or symlinks mv.md libra restoreunstageRestore working tree files or unstage changes from the index restore.md libra cleanRemove untracked files from the working tree (requires -n or -f) clean.md libra stashSave and restore temporary changes with push/pop/list/apply/drop subcommands stash.md libra statusstShow the state of the working tree, staging area, and upstream tracking status.md libra dirtyAdvisory dirty-set marks for the status cache (Libra extension) dirty.md libra revisionRevision ordinal index over first-parent chains (Libra extension) revision.md libra commit-treegit commit-treeCreate a commit object from a tree (plumbing) commit-tree.md libra authHost-scoped HTTP token auth (Libra extension) auth.md libra serviceHeadless local service: notification bus + dirty-mark ingestion (Libra extension) service.md
Command Alias Description Doc libra commitciRecord staged changes as a new commit with optional vault signing and conventional format commit.md libra loghist, historyShow commit history with graph, patch, stat, and custom format support log.md libra logfileInspect the tracing log-file configuration (path, rotation, filter, size) logfile.md libra shortlogslogSummarize reachable commits grouped by author shortlog.md libra showDisplay a commit, tag, tree, blob, or REV:path content show.md libra diffCompare differences between HEAD, index, working tree, or two revisions diff.md libra diff-treeDiff between two trees (git diff-tree) diff-tree.md libra diff-indexDiff a tree against the working tree (git diff-index) diff-index.md libra diff-filesDiff the index against the working tree (git diff-files) diff-files.md libra fast-exportEmit history as a git fast-import stream fast-export.md libra fast-importImport a git fast-import stream fast-import.md libra blameTrace each line of a file to its introducing commit blame.md libra describedescFind the nearest reachable tag and format as tag-N-g<abbrev> describe.md libra grepSearch for patterns in tracked files with regex, revision, and index support grep.md libra reflogView, delete, or check existence of reference change logs reflog.md libra rev-listList commit objects reachable from a revision rev-list.md libra rev-parseParse revision names, abbreviate refs, and print repository paths rev-parse.md
Command Alias Description Doc libra branchbrCreate, delete, rename, list, and inspect branches branch.md libra metadataBranch/repo metadata key-value store (protect/archive/lineage foundation) metadata.md libra tagCreate, list, or delete lightweight and annotated tags tag.md libra switchswSwitch branches, create new branches, or detach HEAD with fuzzy suggestions switch.md libra checkoutBranch compatibility surface and explicit -- path-restore alias; prefer switch / restore checkout.md
Command Alias Description Doc libra resetMove HEAD and optionally reset index or working directory reset.md libra mergeFast-forward merge a branch into the current branch merge.md libra merge-fileThree-way merge of three files (git merge-file) merge-file.md libra merge-baseFind the best common ancestor(s) of two commits merge-base.md libra rebaserbReapply commits on top of another base tip with conflict resolution rebase.md libra cherry-pickcpApply changes from existing commits onto the current branch cherry-pick.md libra revertCreate a new commit that undoes changes from a specified commit revert.md libra replaceSubstitute one object for another on read (refs/replace) replace.md libra rerereReuse recorded conflict resolutions rerere.md libra bisectBinary search to find the commit that introduced a bug; supports start / bad / good / reset / skip / log / run / view bisect.md libra bundleCreate and inspect Git v2 bundle files (create / verify / list-heads) bundle.md
Command Alias Description Doc libra remoteManage remote repositories: add, remove, rename, inspect URLs, prune stale refs remote.md libra fetchDownload objects and update remote-tracking refs from one or all remotes fetch.md libra ls-remoteList references advertised by a remote repository without fetching objects ls-remote.md libra pushSend local commits and objects to a remote with LFS integration push.md libra pullFetch and fast-forward merge into the current branch pull.md libra openOpen the repository's remote URL in the system browser open.md libra lfsManage Large File Storage: track, lock, unlock, list LFS files lfs.md libra credentialVault-backed Git credential helper (fill/store/erase) credential.md libra loginAuthenticate to a Libra host (/api/cli/*) and store a host-scoped session token login.md libra logoutClear stored Libra host session tokens (--all / --local-only) logout.md libra whoamiReport the identity for a stored Libra host session token whoami.md
Command Alias Description Doc libra cloudCloud backup and restore operations via Cloudflare D1/R2 cloud.md libra cacheInspect the tiered-storage / LRU cache configuration (type, threshold, budget) cache.md libra publishManage read-only Cloudflare Worker publishing publish.md libra worktreewtManage multiple working trees attached to the repository worktree.md
Command Alias Description Doc libra codeInteractive TUI with AI agent, web server, and MCP integration code.md libra code-controlDrive a local Libra Code TUI automation control session code-control.md Codex data storage Link libra code --provider codex to Codex app-server and persist Codex session data codex-data-storage.mdlibra automationList, run, and inspect AI automation rules automation.md libra usageReport and prune AI provider/model usage aggregates usage.md libra graphInspect a Libra Code thread version graph in a dedicated TUI graph.md libra sandboxInspect AI sandbox diagnostics, including OS backend availability and downgrade warnings sandbox.md libra agentManage external-agent capture, checkpoints, hooks, and RPC adapters agent.md
Command Alias Description Doc libra applyCheck whether a unified-diff patch applies (--check) apply.md libra cat-fileInspect Git objects and AI objects by type, size, or pretty-printed content cat-file.md libra check-attrReport .libra_attributes attributes (e.g. filter) for pathnames check-attr.md libra check-mailmapResolve Name <email> contacts through .mailmap check-mailmap.md libra check-ignoreReport which pathnames are excluded by .libraignore rules check-ignore.md libra fsckVerify the integrity of objects, refs, and index in a Libra repository fsck.md libra hash-objectCompute Git-compatible blob object IDs from files or standard input hash-object.md libra write-treeWrite the current index out as a tree object write-tree.md libra read-treeRead a tree object into the index (index-only) read-tree.md libra update-indexModify the index directly (add/remove/cacheinfo) update-index.md libra update-refSafely update, create, or delete a branch ref under refs/heads/ update-ref.md libra verify-packValidate pack index files against their pack archives verify-pack.md libra show-refList local refs (branches, tags, HEAD) and their object IDs show-ref.md libra symbolic-refRead or update the symbolic HEAD ref symbolic-ref.md libra index-packBuild a .idx pack index file for an existing .pack archive (hidden) index-pack.md libra hooksExternal AI agent (Claude Code / Gemini) hook entry point; called by configs installed by libra agent enable (hidden) hooks.md
All commands that support --json / --machine return a consistent JSON envelope:
{ "ok" : true , "command" : "<command-name>" , "data" : { ... } } On error:
{ "ok" : false , "command" : "<command-name>" , "error" : { "code" : "LBR-XXX-NNN" , "message" : "Human-readable error description" , "hint" : "Suggested fix or next step" } } Prefix Domain LBR-REPO-*Repository state errors (not a repo, corrupt objects, missing refs) LBR-CLI-*CLI argument validation errors (invalid flags, missing required args) LBR-NET-*Network and transport errors (auth failure, timeout, DNS) LBR-FS-*Filesystem errors (permission denied, disk full, path encoding) LBR-IDX-*Index/staging area errors (corrupt index, lock contention) LBR-OBJ-*Object storage errors (missing object, hash mismatch) LBR-VAULT-*Vault and encryption errors (unseal failure, key generation)
Libra's command-line interface is designed with these principles:
Git compatibility where it makes sense — Most commands mirror Git's flag names and behavior so existing muscle memory transfers directly.Structured output as a first-class citizen — --json and --machine are global flags, and structured output is enabled command-by-command as each surface is modernised. Individual command pages document the currently stable machine-readable contract.SQLite over flat files — Refs, config, and metadata are stored in SQLite for transactional consistency and atomic updates.Security by default — Vault-backed signing and secret encryption are enabled by default, not opt-in.Explicit over implicit — Commands like clean require -f or -n; status --exit-code is an explicit opt-in rather than Git's ambiguous exit code behavior.Actionable errors — Every error includes a stable code (LBR-*), a human-readable message, and a hint for resolution.AI-native development — The libra code command integrates AI agents directly into the version control workflow with multi-provider support and MCP protocol.Cloud-native storage — Built-in tiered storage (S3/R2) and cloud backup (D1/R2) for distributed monorepo workflows.
