fxv command line reference¶

Global options¶

These options can be included with any command.

• --unattended - Unattended mode - Will suppress any user input prompts, but if any options are missing (such as --message for fxv publish) then execution will fail instead of prompting for that option.
• --no-color - No-color mode - Suppresses usage of ANSI colors in output
• --no-pager - No-pager mode - Disable the built in pager for multi-page results. Automatically set if --unattended is set.
• --no-progress - No-progress-bar mode - Disables spinners and progress bars. Automatically set if --unattended is set.
• --format <FORMAT> - Specific output format - This defaults to human which outputs everything human readable. The other option is json. See the output formats section for more information. fxv cat is the one exception: its output is the raw contents of a file, so it accepts only human.

Command List¶

• fxv - runs fxv status by default.
• fxv branch - creates, lists, and switches between branches, and retires the ones you are finished with.
• fxv cat - writes the contents of a single file to standard output.
• fxv changeinfo - shows details about a single revision.
• fxv copy - copies files or directories from another revision into your workspace.
• fxv diff - shows a diff of file changes between revisions.
• fxv doctor - runs diagnostic checks on the environment, workspace, and repository, packages logs for a bug report, and recovers a workspace that fxv resume cannot.
• fxv fetch - downloads what is new in the remote repository into the workspace's local copy, without changing your files.
• fxv goto - moves the whole workspace to another revision, non-destructively.
• fxv history - shows the revision history of the workspace and its repository.
• fxv init - initializes a FlexVault workspace in the current directory.
• fxv login - logs in as a user so publishes are attributed to you.
• fxv logout - logs out, clearing the logged-in user.
• fxv publish - publishes your current draft revision to the repository.
• fxv repo new - creates a new repository in object storage or on the local filesystem.
• fxv repo optimize - merges and compacts a repository's stores to keep it fast.
• fxv repo upgrade - upgrades a repository written by an older version of fxv to the current format.
• fxv resolve - resolves merge conflicts left behind by a fxv sync.
• fxv resume - finishes or undoes a command that was interrupted partway through.
• fxv revert - reverts the workspace, or individual files or directories, to their published base.
• fxv rpc - runs a JSON-RPC server so a program can drive the workspace over a pair of pipes.
• fxv snapshot - commits your current changes to a new draft revision.
• fxv status - shows the current status of the workspace.
• fxv sync - syncs the workspace to the latest published revision, merging your drafts on top.
• fxv upgrade - downloads and installs the newest fxv release, replacing the running executable.
• fxv user - lists and manages users in the repository's user database.

fxv¶

Running fxv with default parameters will automatically run the status command.

Usage:: fxv [OPTIONS] [COMMAND]

fxv branch¶

Commands for managing branches in your workspaces and repositories.

Usage: fxv branch <SUBCOMMAND>

Subcommands:

• new - creates a branch and switches the workspace onto it.
• list - lists branches and this workspace's latest revision on each.
• info - shows the heads, type, owner, and status of one branch.
• switch - moves the workspace onto another branch.
• rename - changes a branch's name, keeping its history and revisions.
• retire - marks a branch as finished, blocking publishes to it.
• restore - reverses a retirement.

A <BRANCH> argument is written in full: a bare name for a global branch, e.g. main, and an owner-prefixed name for a user branch, e.g. alice/fix-shaders. Branch names are 1 to 64 characters of letters, digits, _, -, or spaces, excluding . and /, and cannot start or end with a space.

fxv branch new¶

Creates a branch and, unless --no-switch is given, switches the workspace onto it. The working directory is not touched: uncommitted edits stay on disk and become local changes on the new branch.

Without --global, this creates a user branch owned by you. <NAME> is given without the owner prefix, and the command reports the full name it created, so fxv branch new shaders run as alice creates alice/shaders.

A new branch exists only in your workspace until fxv publish is run on it, and is listed as local only until then.

Usage: fxv branch new <NAME> [OPTIONS]

Arguments:

• <NAME> - the name for the new branch, without an owner prefix. Must not already be in use by one of your own branches, though another user, or the global namespace, may have a branch of that name.

Options:

• --from <REVISION_ID> - the revision the branch starts at, e.g. main.456 or main.456.3. Defaults to the revision the workspace is currently on. Mutually exclusive with --empty.
• --empty - starts the branch with no history and no content, so everything in the workspace becomes a local addition on it. Mutually exclusive with --from.
• --global - creates a global branch instead of a user branch. The revision the branch starts at must be a published revision of a global branch.
• --no-switch - creates the branch and leaves the workspace where it is.

fxv branch list¶

Lists branches with this workspace's latest revision on each, marking the current branch with * and annotating branches that are local only or retired. By default it lists the active global branches and your own.

The two sets of options are independent: one chooses whose branches appear, the other whether retired branches do. Within each set the options are mutually exclusive.

Usage: fxv branch list [OPTIONS]

Options:

• -a, --all - lists every user's branches, not just your own and the global ones.
• -m, --mine - lists only branches you own.
• -o, --owner <USERNAME> - lists only branches owned by that user.
• -g, --global - lists only global branches.
• --include-retired - lists retired branches alongside active ones.
• --only-retired - lists only retired branches.
• --extended - additionally shows each branch's ID, prefixed with #. This is what tells two branches sharing a name apart. --format json always includes it.
• --skip-remote-update - skips checking the remote repository for changes, so the listing shows only what is already in the workspace and does not make any network requests.

A local-only branch that has the same name as a published one can neither be published nor synced. The listing flags it and prints the fxv branch rename --local command to resolve it.

fxv branch info¶

Reports one branch's type, owner, published head, this workspace's latest draft revision on it, and whether it is retired. A branch that has never been published is called out as local to this workspace.

Usage: fxv branch info <BRANCH>

Arguments:

• <BRANCH> - the branch to report on.

Options:

• --skip-remote-update - skips checking the remote repository for changes, so the report shows only what is already in the workspace and does not make any network requests.

fxv branch switch¶

Moves the workspace onto another branch, at this workspace's latest revision of that branch: the latest local draft revision if there is one, otherwise the branch's published head. The revision it arrives at is reported.

Uncommitted edits are snapshotted onto the branch being left before the switch, so they remain on that branch.

Switching onto a retired branch is allowed. Publishing to it is blocked until it is restored.

If this command is interrupted, it can be finished or undone with fxv resume.

Usage: fxv branch switch <BRANCH>

Arguments:

• <BRANCH> - the branch to move onto. A branch with no revisions cannot be switched to.

fxv branch rename¶

Changes what a branch is called. The branch keeps its history, its revisions, and its owner: a branch is identified by an ID that a rename does not touch, so nothing about its contents changes.

Usage: fxv branch rename <BRANCH> <NEW_NAME> [OPTIONS]

Arguments:

• <BRANCH> - the branch to rename.
• <NEW_NAME> - the new name, with or without the branch's own <username>/ prefix. Prefixing it with a different owner's username fails, because a rename changes the name and keeps the owner.

Options:

• -f, --force - required to rename a global branch, which everyone refers to by name.
• --local - renames this workspace's own unpublished branch. Needed only when a published branch has the same name, which is otherwise what <BRANCH> refers to.

The repository's default branch cannot be renamed, with or without --force. Renaming a branch that has not been published yet is local to this workspace.

A revision ID begins with a branch name, so renaming a branch invalidates the IDs anyone wrote down under the old one. alice/fix-shaders.3 stops resolving once that branch becomes alice/water, and the same revision is then alice/water.3.

fxv branch retire¶

Marks a branch as finished. Retiring excludes it from the default fxv branch list output and blocks fxv publish to it. Nothing is deleted, and reading history, switching onto the branch, creating a branch from one of its revisions, and snapshotting on it all continue to work.

On a branch that has not been published, the change stays local to this workspace.

Usage: fxv branch retire <BRANCH> [OPTIONS]

Arguments:

• <BRANCH> - the branch to retire.

Options:

• -f, --force - required to retire a global branch, which affects everyone.

fxv branch restore¶

Reverses a retirement, returning the branch to the default listings and allowing fxv publish to it again.

Usage: fxv branch restore <BRANCH>

Arguments:

• <BRANCH> - the branch to restore.

fxv cat¶

Writes the contents of a single file to standard output. Without --revision the file is read from your workspace as it is on disk. With --revision it is read from the repository as it was at that revision, which is how you read a file that has since been changed or deleted locally.

Usage: fxv cat <PATH> [OPTIONS]

Arguments:

• <PATH> - the file to write out, given as a workspace path.

Options:

• -r, --revision <REVISION_ID> - the revision ID to read the file from (e.g. main.11 or main.11.123). Defaults to the file as it currently exists on disk.

Output is the file's raw bytes with nothing added, so it can be redirected or piped to another tool. Diagnostics go to standard error, and a closed pipe (as in fxv cat big.bin | head -c 16) stops the read rather than failing.

fxv changeinfo¶

Displays information about an existing published revision or draft revision.

Usage: fxv changeinfo <REVISION_ID> [OPTIONS]

Arguments:

• <REVISION_ID> - a revision ID that uniquely identifies a published revision (e.g. main.456) or a draft revision (e.g. main.456.1). Shows details such as the author, creation date, description, and, by default, a list of files that were added, deleted, or modified as part of the revision.

Options:

• -a, --all-files - Show every file that exists in the revision, even if it was not modified.
• -e, --extended-view - Display additional change metadata, including the full commit hash and extended file details.

fxv copy¶

Copies files or directories from another revision into your workspace, and saves the result as a new draft revision. Each file is replaced with its content from the source revision. A directory is replaced with its entire set of files and content from the source revision, and any file in it that does not exist in the source revision is deleted. A path that does not exist in the source revision at all is deleted. However, all of this is non-destructive: the current workspace is snapshotted first, so you can always undo the operation if needed.

The new draft revision does not record which revision the files came from. Its history is the same as if you had made the changes by hand.

Copying a path clears any conflict on it or inside it. A path that is conflicted in the source revision cannot be copied, since its contents are not final and thus ambiguous. The same applies to a path inside a conflicted directory, and to a directory that contains a conflicted path. Only a draft revision can have conflicts. If the result matches the published base, the workspace moves back onto that base (e.g. main.11.0) instead of creating a new draft revision.

If this command is interrupted, it can be finished or undone with fxv resume.

Usage: fxv copy <PATHS>... --from <REVISION_ID>

Arguments:

• <PATHS>... - the files or directories to copy, each given as a workspace path. A path that does not exist in either the source revision or the current draft is an error.

Options:

• --from <REVISION_ID> - the revision ID to copy from, on any branch, e.g. main.11 or main.11.123. A draft revision must be one made in this workspace. A bare branch name such as main is not accepted.

fxv diff¶

Displays a diff view of changes between different revisions of files.

Usage: fxv diff [GLOB_PATTERN] [COMPARE_SPEC] [OPTIONS]

Arguments:

• [GLOB_PATTERN] - a glob pattern to filter which files to diff (e.g. **/*.txt). Defaults to ** (all files).
• [COMPARE_SPEC] - this is a string describing the parameters of the diff.
  • If omitted entirely, the default behavior is for the left half of the diff to be the parent published revision of the matched files, and the right half will be the current version in the workspace.
  • If the spec is a single revision, e.g. main.123 or main.123.3 then the left half of the diff will be the file content at that revision, and the right half will be the current version in the workspace.
  • If the spec is a comma separated pair of revisions, e.g. main.123,main.123.5 then the left half of the diff will be the content at the first revision (e.g. main.123) and the right half will be the content at the second revision (e.g. main.123.5)

Options: None

fxv doctor¶

Runs a set of diagnostic checks covering the local environment, the workspace (if run from inside one), and the repository's integrity, and prints a pass/fail report with suggested fixes for anything actionable. Works both inside and outside a workspace: checks that need one are reported as skipped rather than making the command fail.

Usage: fxv doctor [OPTIONS]

Options:

• --fix - applies automatic remediation for any check found to be safely fixable. In the current version this covers exactly one case: clearing a confirmed-abandoned workspace lock. Everything else is suggest-only.
• --deep - additionally runs a quick integrity validation pass against the current branch's draft head. Off by default, since it is the only check whose cost scales with repository size.

Exits with code 4 when at least one check failed, and 0 otherwise, so a script can run it as a health check without reading the report. Checks that were skipped or produced a warning do not change the exit code.

fxv doctor bundle¶

Runs the same diagnostic checks as fxv doctor (always including the --deep pass) and packages the report, recent logs, and the workspace configuration into a zip file suitable for attaching to a bug report. Nothing is uploaded anywhere; the file is written locally for you to attach yourself.

Usage: fxv doctor bundle [OPTIONS]

Options:

• -o, --output <PATH> - where to write the bundle. Defaults to ./fxv-bugreport-<name>-<timestamp>.zip in the current directory.
• --log-days <N> - how many days of rotated log files to include. Defaults to 3.

fxv doctor reset-sync¶

Recovers a workspace left in an inconsistent state by an interrupted command that fxv resume cannot act on. This happens when the record the interrupted command left behind is damaged and can no longer be read, so FlexVault has no way to tell how far that command got. fxv status reports this case specifically.

The command discards that record and moves the workspace to a revision you choose. Discarding it means the interrupted command can no longer be continued or rolled back. Your files are not at risk: the workspace is snapshotted as a draft revision before anything is moved, so its contents at the time of the reset stay recoverable.

Because the interrupted command's record is unavailable, FlexVault cannot rely on what it knows about the files on disk, and instead reads and re-checks the content of every file it is about to change. This makes a reset considerably slower than an ordinary fxv goto on a large workspace.

Use this only when fxv resume reports that it cannot read the interrupted command. If fxv resume still runs, prefer it.

Usage: fxv doctor reset-sync [OPTIONS]

Options:

• --revision <REVISION_ID> - the revision to move the workspace to, e.g. main.456. Defaults to the latest published revision on the current branch, matching fxv sync.
• --yes - skips the confirmation prompt. Required when running with --unattended, or when standard input is not a terminal.

This command fails if the workspace has no interrupted command to reset.

With --format json, the output's message.kind is doctor-reset-sync, and its payload has the same fields as the output of fxv goto.

fxv fetch¶

Brings the workspace's local copy of the remote repository up to date, downloading everything that is new on the remote. Your files and the workspace's current revision do not change: fxv sync does that.

Commands that need the remote's latest state fetch it themselves, so users typically do not need to run fxv fetch. It exists as a convenience for plugins, integrations, and other external processes, so they can keep the workspace's local copy up to date.

Usage: fxv fetch [OPTIONS]

Options:

• --repair - first downloads again any file of the workspace's local copy that fxv cannot read, so the local copy matches the remote repository. Applies only to a workspace connected to a remote repository. It cannot run while another command is using the workspace, and exits with code 99 if one is.

With --format json, the output's message.kind is fetch, and its payload contains:

• bytes_downloaded - the number of bytes downloaded.
• repaired_files - the files of the local copy that --repair replaced or removed. Empty without --repair, or when nothing was damaged.

fxv goto¶

Moves the entire workspace to an existing revision (published or draft). Non-destructive: the current workspace is snapshotted first, and locally-modified files are preserved as a snapshot rather than clobbered.

If this command is interrupted, it can be finished or undone with fxv resume.

Usage: fxv goto <REVISION_ID>

Arguments:

• <REVISION_ID> - the revision to move the workspace to, e.g. main.11 or main.11.123.

fxv init¶

Initializes a FlexVault workspace in the current directory

Usage: fxv init [OPTIONS] [REMOTE_REPO_URL]

Arguments:

• [REMOTE_REPO_URL] - the URI of an existing FlexVault repository to connect to. Two schemes are supported: s3://<BUCKET>/<PATH> for object storage (for example s3://my-bucket/my-repo) and file://<PATH> for a local filesystem repository (for example file:///home/alice/my-repo or file://../my-repo). A relative file:// path is stored as written and resolved from the workspace directory, not from the directory you run fxv init in, so it only points at the right place when you run fxv init from inside the workspace directory without --path. A workspace linked by a relative path loses its repository if either directory is moved without the other. Not required if the --local-only option is provided. Use fxv repo new to create the repository first.

Options:

• -l, --local-only - creates a workspace with no remote FlexVault repository, such that all changes are stored locally.

  Warning

  Local only repositories DO NOT back up your repository externally by default! This means that if you delete the .fxv_workspace folder in your workspace, your history will be IRREVOCABLY LOST. Where possible, create a repository backed by object storage with fxv repo new and connect to it instead. See Setting up a Shared Repository.

• -p, --path <PATH> - target path at which to create the workspace. Defaults to current directory.

• -f, --force - clears an incomplete workspace at the target path before creating, so a failed fxv init can be retried in place. This never removes a valid workspace, and it only clears the target path itself, never a workspace in a parent directory.

S3 options:

The following options apply when REMOTE_REPO_URL is an S3-compatible URI.

• --s3-access-key-id <KEY_ID> - the S3 access key ID for an account with access to the bucket.
• --s3-secret-access-key <SECRET_KEY> - the S3 secret access key for the account.
• --s3-region <REGION> - the S3 region (e.g. us-east-1), or auto for providers like Cloudflare R2 and Tigris. Omit for providers that do not require a region (e.g. Minio, DigitalOcean, GCS).
• --s3-http-endpoint <URL> - the HTTP endpoint URL for the S3-compatible service. Used verbatim: it must already include the bucket and any path prefix, as FlexVault does not append them. Omit to use the default AWS S3 endpoint for the specified region.

fxv history¶

Show the revision history of the current workspace and/or its remote repository

Usage: fxv history [OPTIONS]

Options:

• -n, --num <NUM> - limit the number of results to the most recent NUM revisions.
• -b, --branch <BRANCH> - which branch to show the history of, written in full, e.g. main or alice/fix-shaders. Defaults to the current branch of the workspace.
• -p, --published-only - only show published revisions, no draft revisions. Cannot be used with --draft-only
• -d, --draft-only - only show local draft revisions, no published revisions. Cannot be used with --published-only
• --skip-remote-update - skips checking the remote repository for changes, so the history shows only what is already in the workspace and does not make any network requests.
• -l, --long - show long descriptions instead of truncated ones
• -e, --extended - display extended information such as commit hashes and timestamps. Implies --long.

fxv login¶

Logs in to this workspace as an existing user, so that fxv publish (and, opportunistically, draft-side commits from fxv snapshot, fxv sync, fxv goto, and fxv resolve) can attribute what you do to a real identity rather than an unattributed local author.

There is no authentication yet - fxv login just validates that the given username refers to an active user in the connected workspace's repository, fetching the latest user database first so the check is against the authoritative published store rather than a possibly-stale local cache.

Usage: fxv login <USERNAME>

Arguments:

• <USERNAME> - the username to log in as, in any case. Must already exist and be active - see fxv user to create one.

fxv logout¶

Logs out of this workspace, clearing the logged-in user. fxv publish will be blocked until fxv login is run again. Succeeds whether or not a user was logged in.

Usage: fxv logout

With --format json, the output's message.kind is logout, and its payload contains:

• was_logged_in - whether a user was logged in before the command ran.
• username - the user that was logged out. Present only when was_logged_in is true.

fxv publish¶

Publishes the current draft revision to the repository, making it a published revision visible to other users.

Publishing to a retired branch is blocked. Bring the branch back with fxv branch restore first.

Usage: fxv publish [OPTIONS]

Options:

• -d, --description <DESCRIPTION> - a description for this publish. If omitted, you will be prompted to enter one.
• --allow-unpublished-origin - publishes a branch whose history descends only from unpublished work. See below.
• --no-triggers - bypasses client-side pre-publish and post-publish triggers.
• --trust-triggers - automatically trusts and approves publish triggers without prompting.

While it runs, the command shows the files and bytes it copies, then the commit. When it finishes, it prints the new published revision and lists the files that revision adds, changes, and deletes.

With --format json, the output's message.kind is publish, and its payload contains:

• published_revision - the revision ID of the new published revision, or null when the branch already matched the draft and there was nothing to publish.
• files_published_count - the number of files the published revision adds, changes, and deletes.
• files_published - those files, each with the change it published.
• bytes_copied - the size of the content the published revision takes from the draft.
• bytes_new - the compressed size of the content that was not in the repository already.

A branch's first publish records the nearest published revision its history descends from. FlexVault walks back through the branch's ancestry to find one, so a branch cut from a local draft revision publishes normally as long as something further back has been published.

fxv publish refuses the branch when nothing in that ancestry has been published. The common way to meet this is branching in a repository before its first publish:

Error: Branch 'alice/feature' descends only from unpublished work, ending at 'main.-.1'.
Merge or sync a published revision into this branch to record what it descends from, or pass
`--allow-unpublished-origin` to publish it without any: its history then starts with no root, permanently.

Publishing anything in the branch's ancestry first, usually the branch it was created from, gives the publish something to record. The published store only appends, so a branch that starts without that link never acquires one afterwards, which is why FlexVault refuses the publish rather than warning about it. --allow-unpublished-origin publishes anyway, for when a branch with no published root is what you intend.

A branch created from nothing has no link to record and is exempt. This covers the repository's default branch and any branch created with fxv branch new --empty.

Publish triggers:

Workspaces can define client-side triggers in .fxv/triggers.toml or triggers.toml that run commands before (pre-publish) or after (post-publish) a publish completes.

Pre-publish triggers validate changes before they are committed to the repository. If any pre-publish trigger exits with a non-zero exit code and has abort_on_failure enabled (the default), the publish is stopped immediately. Post-publish triggers execute after the revision is published to trigger downstream actions or notifications.

To protect against running untrusted scripts, FlexVault computes a cryptographic hash of each trigger definition and prompts for interactive approval the first time the trigger runs or when its configuration changes. Pass --trust-triggers to automatically approve triggers in automated environments, or pass --no-triggers to bypass trigger execution entirely. For complete configuration syntax and filtering rules, see Configure Client-Side Triggers.

fxv repo new¶

Creates a new repository, either in S3-compatible object storage or on the local filesystem, and seeds it with an initial admin user. This is distinct from fxv init, which creates a local workspace against a repository that already exists.

repo is an alias for repository, so fxv repository new is equivalent.

Usage: fxv repo new <URI> --admin-username <USERNAME> [OPTIONS]

Arguments:

• <URI> - where to create the repository. Two schemes are supported:
  • s3://<BUCKET>/<PATH> - an S3-compatible object storage bucket, for example s3://my-bucket/my-repo. Requires the S3 options below.
  • file://<PATH> - a local filesystem directory, for example file:///home/alice/my-repo, file://c:/Users/alice/my-repo, or file://./my-repo. The path can be absolute or relative to the current directory, and the directory must already exist.

Options:

• --admin-username <USERNAME> - required. Username for the initial admin user seeded into the new repository. Same rules as fxv user add: 1-32 characters of ASCII letters, digits, _, -, or ., stored in lowercase.
• --admin-display-name <NAME> - display name for the initial admin user. Defaults to the username as you typed it, before it is converted to lowercase.
• --admin-email <EMAIL> - email address for the initial admin user.

S3 options:

These apply when <URI> uses the s3:// scheme, and are ignored for file:// repositories.

• --s3-access-key-id <KEY_ID> - the S3 access key ID for an account with access to the bucket.
• --s3-secret-access-key <SECRET_KEY> - the S3 secret access key for the account.
• --s3-region <REGION> - the S3 region (e.g. us-east-1), or auto for providers like Cloudflare R2 and Tigris. Omit for providers that do not require a region (e.g. Minio, DigitalOcean, GCS).
• --s3-http-endpoint <URL> - the HTTP endpoint URL for the S3-compatible service. Used verbatim: it must already include the bucket and any path prefix, as FlexVault does not append them. Omit to use the default AWS S3 endpoint for the specified region.

fxv repo optimize¶

Merges and compacts a repository's stores. FlexVault appends new files as work is published rather than rewriting existing ones, so repositories slow down over time as content metadata spreads across more and more files. Optimization consolidates them.

Works against both local filesystem and object storage repositories. Credentials for an object storage repository are read from the repository configuration, so no --s3-* options are needed.

Usage: fxv repo optimize <REPO_PATH> [LEVEL]

Arguments:

• <REPO_PATH> - path to the repository directory to optimize. Inside a workspace this is usually .fxv_workspace/published_repo for the published repository, or .fxv_workspace/draft_repo for the local draft store. A standalone repository created with fxv repo new file:///... can be given by its own path.
• [LEVEL] - how thorough the optimization should be. Defaults to quick.
  • quick - merges the store without discarding stale data or repacking files. Faster, but leaves some redundancy behind.
  • full - additionally removes duplicate data and repacks files. Slower, and the better choice when time allows.

Optimization can run while other FlexVault commands use the repository, and the repository remains in a valid state throughout. It is refused while the repository is being repaired or upgraded, with advice to try again once that has finished.

With --format json, the output's message.kind is repo-optimize, and its payload contains bytes_processed, the bytes of store files merged, and namespaces, with one entry for each of the repository's stores. Each entry has the store's namespace, its own bytes_processed, and skipped, which is true when that store did not need merging.

See Maintain Your Repository for guidance on how often to run it.

fxv repo upgrade¶

Upgrades a repository written by an older version of fxv to the current format. Until a repository is upgraded, commands that use it exit with code 96. See Upgrade Your Repository for when to run it and how to prepare.

Without <URI>, the command upgrades the repositories of the workspace in the current directory: the repository it publishes to, starting with the remote repository if it has one, and then the workspace's own data. Every other workspace of the repository needs the same command. With <URI>, only the repository there is upgraded.

Before it upgrades a repository that other workspaces use, the command asks for confirmation, since older versions of fxv can no longer use the repository afterwards. If an upgrade is interrupted, running the same command again finishes it.

To update fxv itself, see fxv upgrade.

Usage: fxv repo upgrade [URI] [OPTIONS]

Arguments:

• [URI] - the repository to upgrade: file://<PATH> for a local repository, or s3://<BUCKET>/<PATH> for a remote one, which needs the S3 options below. A workspace's own repositories cannot be given by path: run the command inside that workspace instead.

Options:

• --yes - skips the confirmation prompt. Required when running with --unattended, or when standard input is not a terminal.

S3 options:

These apply only when <URI> uses the s3:// scheme, and are the same as for fxv repo new: --s3-access-key-id, --s3-secret-access-key, --s3-region, and --s3-http-endpoint.

fxv resolve¶

Resolves conflicted files left behind by a fxv sync merge, either keeping your local draft content or taking the published revision's. While any conflicts remain unresolved, you will be unable to publish your changes.

If this command is interrupted, it can be finished or undone with fxv resume.

Usage: fxv resolve (--mine|--theirs|--undo) (--all | [FILES]...)

Arguments:

• [FILES]... - the conflicted files to act on, each given as a workspace path. Mutually exclusive with --all.

Options:

• --mine (aliases: --draft, --local) - keep your local draft content for the given conflicts.
• --theirs (aliases: --published, --remote) - take the published revision's content for the given conflicts.
• --undo - restore the conflict state recorded by the last sync merge, undoing earlier resolutions so they can be revisited.
• --all - act on every conflicted file instead of listing them individually.

Exactly one of --mine, --theirs, or --undo must be given.

fxv resume¶

Recovers a fxv sync, fxv goto, fxv revert, fxv resolve, fxv branch switch or fxv copy command that was interrupted before it finished. An interrupted command leaves the workspace part-way between two revisions, in what is called an inconsistent state. In this state, most commands that read or change workspace state will not run until the inconsistent state is resolved.

There are two ways to return the workspace to a consistent state after an interruption. The first is the default, "continuing", triggered by running fxv resume or fxv resume --continue - this continues the interrupted operation where it left off. The other option is "rolling back", triggered by fxv resume --rollback. Rolling back, as the name suggests, rolls back the interrupted operation and returns the workspace to the revision it was on before. Both are safe to interrupt again: an interrupted recovery is itself resumable.

Like other FlexVault operations, this operation is safe - any local edits it finds are moved aside and committed as a draft revision rather than overwritten.

Usage: fxv resume [--continue | --rollback] [--full]

Options:

• --continue - finish the interrupted operation. This is the default when no option is given.
• --rollback - undo the interrupted operation, returning the workspace to the revision it was on before it started.
• --full - this will fully re-check and re-sync every file in the interrupted operation's plan, even those marked as finished, and as a result is much slower than a normal resume. Typically not required, but may be useful in cases where the operation was interrupted by a catastrophic event like a hard power loss.

This command fails if there are no interrupted operations pending. To check if a workspace is consistent, run fxv status.

If the record the interrupted command left behind is damaged, neither continuing nor rolling back can read it, and fxv resume says so. Recover with fxv doctor reset-sync instead.

fxv revert¶

Restores the whole workspace (--all), or individual files or directories, to their published base. Files and directories that are new in the draft are removed. Reverting a path clears any conflict on it or inside it. Non-destructive: the current workspace is snapshotted first.

If this command is interrupted, it can be finished or undone with fxv resume.

Usage: fxv revert (--all [--force] | [FILES]...)

Arguments:

• [FILES]... - the files or directories to revert to their published base, each given as a workspace path. Mutually exclusive with --all.

Options:

• --all - revert the entire workspace to its published base (e.g. from main.11.123 back to main.11.0).
• --force - with --all on a draft that has no published base, revert to an empty tree instead of erroring.

fxv rpc¶

Runs a JSON-RPC 2.0 server that operates on a workspace, reading one request per line from standard input and writing one response per line to standard output. It serves a single connection and exits when that connection ends, so a client starts it as a child process rather than connecting to a running service.

This is an alternative to running an fxv process per command, intended for a long-running program that queries the same workspace repeatedly. It answers a subset of the commands available on the command line. See the RPC section for the protocol, the method set, and the error codes.

Usage: fxv rpc [OPTIONS]

Options:

• --working-dir <PATH> - the workspace this server operates on, which may be any directory inside it. Defaults to the current directory. Fixed for the life of the server: requests cannot override it.

fxv snapshot¶

Commit current changes to a draft revision on the current branch.

Usage: fxv snapshot [OPTIONS]

Options:

• -d, --description <DESCRIPTION> - An optional description for this snapshot. If the <DESCRIPTION> parameter is omitted, you will be prompted for the description.

Snapshotting works on a retired branch. The command warns that publishing to that branch is blocked and saves the work anyway.

fxv status¶

Shows information about the current status of the workspace, including the current branch, parent published revision, and any draft revisions that have been made.

Usage: fxv status [OPTIONS]

Options:

• --skip-scan - skips scanning the workspace for untracked files, so only tracked files are reported.
• --skip-remote-update - skips checking the remote repository for changes, so status reports only what is already in the workspace and does not make any network requests. Useful for checking status frequently, as editor plugins do.

With --format json, a workspace that has not synced yet on a branch that has published revisions, as right after fxv init, reports a head_commit of empty_branch with a published_head field giving the branch's latest published revision.

fxv sync¶

Syncs your workspace to the specified published revision of your current branch. If no revision is specified, it will sync to the branch's latest published revision. Any unpublished draft changes in your workspace are merged on top of the target revision as a new draft revision (e.g. syncing a draft based on main.3 to main.5 lands on main.5.1). This command always pre-snapshots your current draft revisions before syncing, so you can always go back to your current state if needed.

If this command is interrupted, it can be finished or undone with fxv resume.

Usage: fxv sync [REVISION_ID]

Arguments:

• [REVISION_ID] - an optional published revision ID spec on your current branch, for example main.3 (the draft alias main.3.0 is also accepted). If this argument is omitted, the workspace syncs to the latest published revision of your current branch.

fxv upgrade¶

Downloads and installs the newest fxv release for your configured channel, replacing the running executable.

By default, prints the version you would move to and asks for confirmation before downloading anything. The downloaded binary is verified against its published checksum before install; if verification fails, or the install itself fails partway, the previous binary is left in place rather than removed.

Release channels:

FlexVault distributes releases across two channels:

• stable (default): Production releases that have completed quality assurance. Most users should stay on the stable channel unless instructed by the FlexVault team for dedicated feature and bug fix testing.
• beta: Pre-release builds containing newly merged changes and fixes intended for early validation.

When checking for updates or switching channels, fxv upgrade guards against unintentional downgrades. If moving to a target version lower than your currently installed binary (such as switching from a newer beta back to stable), the command prompts for confirmation unless --yes is passed.

Usage: fxv upgrade [OPTIONS]

Options:

• -y, --yes - skips the confirmation prompt and installs immediately. Required when running non-interactively (for example, with no terminal attached, --unattended, or --format json).
• --channel <CHANNEL> - query a specific release channel (stable or beta) for this invocation without changing your persisted default.
• --set-channel <CHANNEL> - set and persist your default release channel (stable or beta) for this and future invocations. Mutually exclusive with --channel.
• --check - inspect available updates and check registered integration compatibility without downloading or installing.
• --to <VERSION> - upgrade or downgrade to a specific version instead of the latest release on the channel.
• --allow-incompatible - proceed with installation even if the candidate version exceeds registered integration compatibility ceilings.

If you are already on the latest release for your channel, fxv upgrade reports Already up to date and exits without changing anything.

fxv user¶

Manages users in the connected workspace's canonical (published) user database. A user must exist here, and be logged in via fxv login, before fxv publish will work.

Usage: fxv user <SUBCOMMAND>

Subcommands:

• add <USERNAME> [OPTIONS] - adds a new user.
  • <USERNAME> - 1-32 characters: ASCII letters, digits, _, -, or .. Must be unique among active users, ignoring case.
  • --display-name <NAME> - display name for the user. Defaults to the username as you typed it, before it is converted to lowercase.
  • --email <EMAIL> - email address for the user.
• edit <USERNAME> [OPTIONS] - edits an existing user. Only the fields you pass are changed.
  • <USERNAME> - the current username of the user to edit.
  • --rename <NEW_USERNAME> - renames the user.
  • --display-name <NAME> - sets a new display name.
  • --email <EMAIL> - sets the user's email address. Mutually exclusive with --clear-email.
  • --clear-email - clears the user's email address. Mutually exclusive with --email.
• deactivate <USERNAME> - deactivates a user. The user is retained (its id stays valid, so past commits keep their attribution) but is excluded from active lookups, is no longer a valid fxv login target, and frees up its username for reuse.
• list [OPTIONS] - lists the users in the user database with their display names and email addresses, ordered by username. The user this workspace is logged in as is marked with *. Deactivated users are listed only with --include-deactivated or --only-deactivated.
  • --include-deactivated - lists deactivated users alongside active ones, marked (deactivated). Mutually exclusive with --only-deactivated.
  • --only-deactivated - lists only deactivated users. Mutually exclusive with --include-deactivated.
  • --skip-remote-update - skips checking the remote repository for changes, so the listing shows only what is already in the workspace and does not make any network requests.

Usernames are case-insensitive: Alice and alice are the same user. You can type a username in any case wherever a command asks for one, including fxv login, fxv branch list --owner, and the owner in a branch name such as alice/fix-shaders. Usernames are stored and shown in lowercase. A display name is stored as you type it.

With --format json, the output of fxv user list has a message.kind of user-list, and its payload contains users, a list in which each user has:

• id - the user's numeric ID, which does not change when the user is renamed.
• username - the username, in lowercase.
• display_name - the display name.
• email - the email address. Absent when the user does not have an email address.
• deactivated - whether the user has been deactivated.
• current - whether this workspace is logged in as this user.

Exit Codes¶

See Exit Codes for the codes fxv exits with and what each one means.

Output Formats¶

There are two output formats, chosen with the --format global option.

• human (default)¶

  This is the default, human readable output.

• json¶

  A single JSON object, printed when the command finishes. It has two fields:

  • program - details of the fxv process that produced it, including its version and arguments.
  • message - the command's result:
    • kind - the command that produced the result, as its command path joined by dashes, such as status or user-add. A failed command reports error instead, with a payload containing the error message and the exit_code. See Exit Codes.
    • version - the version of the payload's format, as a major.minor string. The minor version increases when fields are added, and the major version when a change could break a consumer.
    • payload - the result itself. Its fields depend on kind.
    • warnings - conditions the command continued past, such as a failed check for changes in the remote repository, each with the message and advice it would get as a failure. Absent when there are none.