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 options are json and json-streaming. 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 cat - writes the contents of a single file to standard output.
• fxv changeinfo - shows details about a single revision.
• 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 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 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, 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 - 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 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 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.

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.

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:///<ABSOLUTE_PATH> for a local filesystem repository (for example file:///home/alice/my-repo). 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 Getting Started with the CLI.

• -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. 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
• -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. 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.

Usage: fxv logout

fxv publish¶

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

Usage: fxv publish [OPTIONS]

Options:

• -d, --description <DESCRIPTION> - a description for this publish. If omitted, you will be prompted to enter one.

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:///<ABSOLUTE_PATH> - a local filesystem directory, for example file:///home/alice/my-repo. The path must be absolute 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 lowercase letters, digits, _, -, or ..
• --admin-display-name <NAME> - display name for the initial admin user. Defaults to the username if omitted.
• --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 is safe to run concurrently with other FlexVault operations; the repository remains in a valid state throughout. See Maintain Your Repository for guidance on how often to run it.

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 or fxv resolve 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, to their published base. Files that are new in the draft are removed. 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 to revert to their published-base content, 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.

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: None

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/rebased 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, replacing the running executable. Always installs the latest available release, regardless of the version you are currently running.

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.

Usage: fxv upgrade [OPTIONS]

Options:

• -y, --yes - skips the confirmation prompt and installs immediately. Required when running non-interactively, e.g. no terminal attached, --unattended, or --format json.

If you are already on the latest release, 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: lowercase letters, digits, _, -, or .. Must be unique among active users.
  • --display-name <NAME> - display name for the user. Defaults to the username if omitted.
  • --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.

Output Formats¶

There are currently several options for output formats.

• human (default)¶

  This is the default, human readable output

• json¶

  This format will output a single JSON blob at the end of execution describing the output.

• json-streaming¶

  This format will periodically output JSONL content (line-delimited JSON objects) such that progress can be tracked over time.