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.

Command List¶

• fxv - runs fxv status by default.
• fxv changeinfo - shows details about a single revision.
• fxv diff - shows a diff of file changes between revisions.
• 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 restore - restores the workspace to a specific draft snapshot.
• fxv revert - reverts the workspace, or individual files, to their published base.
• 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 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 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 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.

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.

• -p, --path <PATH> - target path at which to create the workspace. Defaults to current 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 names 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.

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

Arguments:

• [FILES]... - the workspace-relative conflicted files to act on. 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 naming them.

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

fxv restore¶

Restores your workspace to a specific draft snapshot.

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.

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

Arguments:

• [FILES]... - the workspace-relative files to revert to their published-base content. 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 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.

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