Command Reference - Byterover

Command Overview

All commands are available in two modes:

CLI: brv vc <command> [args] [flags]
TUI (REPL): /vc <command> [args] [flags]

Both modes accept the same arguments and flags. The examples below use the CLI format — replace brv vc with /vc for TUI usage.

Setup Commands

vc init

Initialize version control for the current space.

brv vc init


Arguments	None
Flags	None
Returns	Git directory path, whether it was reinitialized
Prerequisites	A ByteRover space must exist (`.brv/` directory)

Safe to re-run — reports “reinitialized” without losing history. Errors: ALREADY_INITIALIZED

vc config

Get or set commit author identity. Configuration is local to the current space — each space maintains its own author identity.

brv vc config <key> [value]

Argument	Required	Description
`key`	Yes	`user.name` or `user.email`
`value`	No	Value to set. Omit to read the current value

Set a value:

brv vc config user.name "Alice Chen"
brv vc config user.email "alice@example.com"

Read a value:

brv vc config user.name
# Output: Alice Chen

brv vc config user.email
# Output: alice@example.com

Errors: INVALID_CONFIG_KEY, CONFIG_KEY_NOT_SET, GIT_NOT_INITIALIZED

vc clone

Clone a remote space from ByteRover cloud.

brv vc clone <url>

Argument	Required	Description
`url`	Yes (optional in TUI)	`https://byterover.dev/<team>/<space>.git`


Returns	Git directory, team name, space name
Timeout	120 seconds
TUI only	Omit URL to open an interactive space picker

brv vc clone https://byterover.dev/acme/project.git

Errors: CLONE_FAILED, AUTH_FAILED, INVALID_REMOTE_URL

Staging & History Commands

vc add

Stage files for the next commit.

brv vc add [files...]

Argument	Required	Description
`files`	No	File or directory paths to stage. Defaults to `.` (everything)

Accepts zero or more paths. Paths are relative to the context tree root.

brv vc add .                                  # stage everything
brv vc add notes.md                           # stage one file
brv vc add design/architecture.md docs/       # stage multiple paths
brv vc add authentication/                    # stage an entire directory

Errors: GIT_NOT_INITIALIZED, FILE_NOT_FOUND

vc commit

Save staged changes as a commit.

brv vc commit -m "<message>"

Flag	Required	Description
`-m`, `--message`	Yes	Commit message (no auto-generation)


Returns	Short SHA (7 characters) and commit message
Prerequisites	`user.name` and `user.email` configured, at least one file staged

brv vc commit -m "add JWT token rotation patterns"
brv vc commit -m "reorganize database domain into separate topics"

Errors: USER_NOT_CONFIGURED, NOTHING_STAGED, GIT_NOT_INITIALIZED

vc status

Show working tree status.

brv vc status


Arguments	None
Flags	None

Returns:

Field	Description
Current branch	The branch you are on
Tracking info	Ahead/behind upstream count
Merge state	Whether a merge is in progress
Staged changes	Files ready to commit
Unstaged changes	Modified files not yet staged
Untracked files	New files not being tracked
Unmerged paths	Files with conflicts during a merge
Conflict markers	Files containing `<<<<<<<`/`=======`/`>>>>>>>`

vc diff

Show changes between commits, the index, or the working tree.

brv vc diff [ref] [--staged]

Argument	Required	Description
`ref`	No	A commit, branch, or `<ref1>..<ref2>` range. Omit to diff the working tree against the index

Flag	Default	Description
`--staged`	`false`	Show staged changes (HEAD vs index) instead of unstaged

The ref argument decides what is being compared:

Form	Compared
`brv vc diff`	Working tree vs index (unstaged changes)
`brv vc diff --staged`	Index vs HEAD (staged changes)
`brv vc diff <commit>`	Working tree vs `<commit>`
`brv vc diff <ref1>..<ref2>`	`<ref1>` vs `<ref2>` (commit-to-commit or branch-to-branch)

brv vc diff                          # unstaged changes vs HEAD
brv vc diff --staged                 # staged changes vs HEAD
brv vc diff HEAD~1                   # working tree vs the previous commit
brv vc diff main                     # working tree vs the main branch
brv vc diff main..feature/x          # compare two branches

Also available in the TUI as /vc diff with the same arguments and flags. Errors: INVALID_REF, GIT_NOT_INITIALIZED

vc log

Show commit history.

brv vc log [branch] [--all] [--limit N]

Argument	Required	Description
`branch`	No	Show history for a specific branch

Flag	Default	Description
`--all`, `-a`	`false`	Show commits from all branches
`--limit`	`10`	Maximum number of commits to display

Each log entry includes: SHA, message, author (name + email), timestamp.

brv vc log                        # last 10 commits on current branch
brv vc log --limit 20             # last 20 commits
brv vc log feature/auth           # history of a specific branch
brv vc log --all                  # all branches
brv vc log --all --limit 50       # combine flags

Errors: NO_COMMITS, BRANCH_NOT_FOUND, GIT_NOT_INITIALIZED

vc reset

Unstage files or undo commits.

brv vc reset [files...]           # unstage files
brv vc reset --soft [ref]         # undo commits, keep staged (ref defaults to HEAD)
brv vc reset --hard [ref]         # reset working tree & staging (ref defaults to HEAD)

Argument	Required	Description
`files`	No	Specific files to unstage

Flag	Description
`--soft`	Move HEAD back, keep changes in staging area
`--hard`	Move HEAD back, discard all changes (destructive)

--soft and --hard are mutually exclusive.

Mode	HEAD	Staging	Working Tree
No flags	Unchanged	Cleared	Unchanged
`--soft`	Moved back	Preserved	Unchanged
`--hard`	Moved back	Cleared	Cleared

brv vc reset                       # unstage all files
brv vc reset notes.md              # unstage specific file
brv vc reset --soft HEAD~1         # undo last commit, keep staged
brv vc reset --soft HEAD~3         # undo last 3 commits, keep staged
brv vc reset --hard                # discard all uncommitted changes
brv vc reset --hard HEAD~1         # undo last commit, discard changes

Errors: INVALID_REF, NOTHING_TO_RESET, GIT_NOT_INITIALIZED

Branching Commands

vc branch

List, create, or delete branches.

brv vc branch [name] [flags]

Argument	Required	Description
`name`	No	Branch name to create

Flag	Description
`-a`, `--all`	List all branches including remote-tracking
`-d`, `--delete`	Delete a branch by name
`--set-upstream-to`	Set upstream tracking for current branch (e.g., `origin/main`)

List branches:

brv vc branch                                # local branches (* = current)
brv vc branch -a                             # all branches including remote

Create a branch:

brv vc branch feature/new                    # create (doesn't switch to it)

Delete a branch:

brv vc branch -d feature/old                 # delete (can't delete current)

Set upstream:

brv vc branch --set-upstream-to origin/main  # link to remote branch

Errors: BRANCH_ALREADY_EXISTS, BRANCH_NOT_FOUND, BRANCH_NOT_MERGED, CANNOT_DELETE_CURRENT_BRANCH, INVALID_BRANCH_NAME

vc checkout

Switch to an existing branch, or create and switch in one step.

brv vc checkout <branch> [-b] [--force]

Argument	Required	Description
`branch`	Yes	Branch to switch to (or create with `-b`)

Flag	Default	Description
`-b`, `--create`	`false`	Create the branch before switching
`--force`	`false`	Discard uncommitted changes and force switch

brv vc checkout main                         # switch to main
brv vc checkout -b feature/new-branch        # create and switch
brv vc checkout --force main                 # discard changes and switch

Errors: BRANCH_NOT_FOUND, UNCOMMITTED_CHANGES, BRANCH_ALREADY_EXISTS (with -b)

vc merge

Merge a branch into the current branch.

brv vc merge [branch] [-m "message"] [--abort] [--continue] [--allow-unrelated-histories]

Argument	Required	Description
`branch`	No	Branch to merge (not needed with `--abort`/`--continue`)

Flag	Description
`-m`, `--message`	Custom merge commit message
`--abort`	Cancel current merge and restore pre-merge state
`--continue`	Complete merge after resolving conflicts
`--allow-unrelated-histories`	Allow merging branches with no common ancestor

--abort and --continue are mutually exclusive. Start a merge:

brv vc merge feature/auth                     # merge with default message
brv vc merge -m "merge auth" feature/auth     # custom commit message

Handle conflicts:

brv vc merge --continue                       # opens editor for message
brv vc merge --continue -m "resolve conflicts" # inline message
brv vc merge --abort                          # cancel the merge

Unrelated histories:

brv vc merge --allow-unrelated-histories imported/legacy

Errors: MERGE_CONFLICT, MERGE_IN_PROGRESS, NO_MERGE_IN_PROGRESS, CONFLICT_MARKERS_PRESENT, ALLOW_UNRELATED_HISTORIES

Remote Commands

vc remote

Show, add, update, or remove the remote connection.

brv vc remote                           # show current remote
brv vc remote add <name> <url>          # add a new remote
brv vc remote set-url <name> <url>      # update existing remote URL
brv vc remote remove <name>             # delete the remote

Only origin is supported as a remote name. URLs must match: https://byterover.dev/<team>/<space>.git Show:

brv vc remote
# Output: https://byterover.dev/acme/project.git

Add:

brv vc remote add origin https://byterover.dev/acme/project.git

Update:

brv vc remote set-url origin https://byterover.dev/acme/new-project.git

Remove:

brv vc remote remove origin
# Output: Remote 'origin' removed.

After removing the remote, brv vc push, brv vc pull, and brv vc fetch will fail with NO_REMOTE until you add it again. Errors: REMOTE_ALREADY_EXISTS, INVALID_REMOTE_URL, NO_REMOTE

vc fetch

Fetch refs from ByteRover cloud without modifying local branches.

brv vc fetch [remote] [branch]

Argument	Required	Description
`remote`	No	Remote name (`origin` only). Defaults to `origin`
`branch`	No	Specific branch to fetch. Defaults to all branches


Timeout	120 seconds
Effect	Updates remote-tracking branches only; working tree unchanged

brv vc fetch                     # fetch all branches
brv vc fetch origin              # same as above (origin is default)
brv vc fetch origin main         # fetch only the main branch

Errors: FETCH_FAILED, NO_REMOTE, AUTH_FAILED

vc pull

Pull commits from ByteRover cloud (fetch + merge).

brv vc pull [remote] [branch] [--allow-unrelated-histories]

Argument	Required	Description
`remote`	No	Remote name (`origin` only). Defaults to `origin`
`branch`	No	Branch to pull. Defaults to upstream of current branch

Flag	Default	Description
`--allow-unrelated-histories`	`false`	Allow merging unrelated histories


Timeout	120 seconds
Effect	Fetches and merges into current branch

brv vc pull                                              # pull from upstream
brv vc pull origin main                                  # pull specific branch
brv vc pull --allow-unrelated-histories origin main      # merge unrelated

Errors: PULL_FAILED, NO_REMOTE, NO_UPSTREAM, MERGE_CONFLICT, AUTH_FAILED

vc push

Push commits to ByteRover cloud.

brv vc push [remote] [branch] [-u]

Argument	Required	Description
`remote`	No	Remote name (`origin` only). Defaults to `origin`
`branch`	No	Branch to push. Defaults to current branch

Flag	Default	Description
`-u`, `--set-upstream`	`false`	Set remote branch as upstream tracking


Timeout	120 seconds
Returns	Branch name, up-to-date status, upstream-set status

Push semantics:

brv vc push                          # current branch → upstream
brv vc push -u origin main            # push main and set upstream tracking
brv vc push origin                   # current branch → origin
brv vc push origin feat/x            # feat/x → origin
brv vc push feat/x                   # ERROR: "feat/x" is not a valid remote

Errors: PUSH_FAILED, NON_FAST_FORWARD, NOTHING_TO_PUSH, NO_REMOTE, NO_UPSTREAM, AUTH_FAILED

Error Code Reference

Complete list of error codes across all commands:

Initialization Errors

Error Code	Description	Solution
`ALREADY_INITIALIZED`	VC already set up	Safe to ignore
`GIT_NOT_INITIALIZED`	VC not initialized	Run `vc init`

Configuration Errors

Error Code	Description	Solution
`USER_NOT_CONFIGURED`	Author identity not set	Set `user.name` and `user.email` with `vc config`
`CONFIG_KEY_NOT_SET`	Requested key has no value	Set it with `vc config <key> <value>`
`INVALID_CONFIG_KEY`	Key is not `user.name` or `user.email`	Use a supported key

Staging & Commit Errors

Error Code	Description	Solution
`NOTHING_STAGED`	No files in staging area	Stage files with `vc add`
`NOTHING_TO_RESET`	No changes to unstage	Working tree is clean
`FILE_NOT_FOUND`	Specified file doesn’t exist	Check the file path
`INVALID_REF`	Git ref doesn’t exist	Verify with `vc log`
`NO_COMMITS`	No commits in history	Create your first commit

Branch Errors

Error Code	Description	Solution
`BRANCH_NOT_FOUND`	Branch doesn’t exist	Check names with `vc branch`
`BRANCH_ALREADY_EXISTS`	Branch name is taken	Choose a different name
`CANNOT_DELETE_CURRENT_BRANCH`	On the branch being deleted	Switch to another branch first
`BRANCH_NOT_MERGED`	Branch has unmerged commits	Merge the branch first, or verify you no longer need those commits
`INVALID_BRANCH_NAME`	Invalid characters in name	Use alphanumeric, `/`, `-`, `_`, `.`
`UNCOMMITTED_CHANGES`	Uncommitted changes block operation	Commit changes or use `--force`
`NO_BRANCH_RESOLVED`	Could not determine which branch to operate on	Specify the branch explicitly or check out a branch first

Merge Errors

Error Code	Description	Solution
`MERGE_CONFLICT`	Conflicting changes detected	Resolve conflicts, then `vc merge --continue`
`MERGE_IN_PROGRESS`	A merge is already underway	`--continue` or `--abort` first
`NO_MERGE_IN_PROGRESS`	No active merge to continue/abort	Nothing to do
`CONFLICT_MARKERS_PRESENT`	Unresolved markers in files	Remove all `<<<<<<<`/`=======`/`>>>>>>>` markers
`UNRELATED_HISTORIES`	No common ancestor between branches	Add `--allow-unrelated-histories` flag

Remote & Sync Errors

Error Code	Description	Solution
`NO_REMOTE`	No remote configured	`vc remote add origin <url>`
`REMOTE_ALREADY_EXISTS`	Remote `origin` already set	Use `vc remote set-url` to update
`INVALID_REMOTE_URL`	URL format is wrong	Use `https://byterover.dev/<team>/<space>.git`
`NO_UPSTREAM`	No upstream tracking branch	Use `vc push -u origin <branch>` or `vc branch --set-upstream-to`
`NON_FAST_FORWARD`	Remote has newer commits	Pull first, resolve conflicts, then push
`NOTHING_TO_PUSH`	No new local commits	Already up to date
`CLONE_FAILED`	Clone operation failed	Check URL and network connection
`FETCH_FAILED`	Fetch operation failed	Check network connection
`PULL_FAILED`	Pull operation failed	Check network connection
`PUSH_FAILED`	Push operation failed	Check network connection
`NETWORK_ERROR`	Network connectivity issue	Check your internet connection and try again
`AUTH_FAILED`	Authentication failed	Log in with `brv login` and verify access

Legacy Command Errors

Error Code	Description	Solution
`VC_GIT_INITIALIZED`	Legacy `brv push`/`brv pull` used after `vc init`	Use `brv vc push` / `brv vc pull` instead. See Migration

​Command Overview

​Setup Commands

​vc init

​vc config

​vc clone

​Staging & History Commands

​vc add

​vc commit

​vc status

​vc diff

​vc log

​vc reset

​Branching Commands

​vc branch

​vc checkout

​vc merge

​Remote Commands

​vc remote

​vc fetch

​vc pull

​vc push

​Error Code Reference

​Initialization Errors

​Configuration Errors

​Staging & Commit Errors

​Branch Errors

​Merge Errors

​Remote & Sync Errors

​Legacy Command Errors