Skip to content

Getting Started with the CLI

This guide takes you from an empty terminal to your first publish. You will install the fxv command-line tool, create a repository backed by object storage, connect a local workspace to it, and publish your first change.

If you prefer a graphical workflow or work in a game engine, see Getting Started with FlexVault Desktop instead.

Install the CLI

Install fxv using the install script for your operating system:

irm https://fxv.dev/install.ps1 | iex

The script downloads the latest release, verifies its SHA-256 checksum, installs fxv.exe into %LOCALAPPDATA%\fxv\bin, and adds that directory to your user PATH.

Open a new terminal window for the updated PATH to take effect.

curl -fsSL https://fxv.dev/install.sh | bash

The script installs fxv into ~/.local/bin and adds that directory to your shell configuration if needed.

macOS builds are planned but not published yet. Check fxv.dev/download for updates.

Windows Defender and SmartScreen warnings

Because release binaries are newly published, Windows Defender or SmartScreen may display a warning ("Windows protected your PC") when running install.ps1 or fxv.exe for the first time. Click More info and then Run anyway to proceed.

Confirm the installation:

fxv --help

To update fxv later, run fxv upgrade.

Set up a repository

A FlexVault repository lives in an S3-compatible object storage bucket, which FlexVault talks to directly using the S3 API. This guide uses AWS S3. Set up a Remote Repository compares the recommended providers (AWS S3, Google Cloud Storage, Cloudflare R2, and Tigris) and gives the exact settings for each.

Placeholders in examples

Values in capitals, such as KEY_ID, SECRET_KEY, and REGION, are placeholders to replace with your own. Examples come in Linux/macOS and Windows PowerShell variants; picking one switches every example on this page.

Direct S3 mode is an interim setup

Connecting to a bucket with S3 credentials is called direct S3 mode. It is fully supported today, but FlexVault does not yet have its own authentication layer, so anyone with the bucket credentials has full access to the repository. A dedicated authentication layer is planned. Once it lands, direct S3 mode will remain supported but will no longer be the recommended way to run a shared repository.

Working on a local project?

You do not need a cloud provider at all. A repository can live on your local filesystem using a file:// URI, which is a good fit for solo projects or for trying FlexVault out. See Set up a Local Filesystem Repository.

Create a bucket with your provider and generate an access key ID and secret access key with read and write access to it. Then create the repository with fxv repo new. The --admin-username is required: it seeds the repository's first user, who is recorded as the initial administrator.

fxv repo new s3://my-bucket/my-repo \
  --admin-username alice --admin-email [email protected] \
  --s3-access-key-id KEY_ID \
  --s3-secret-access-key SECRET_KEY \
  --s3-region REGION

fxv repo new s3://my-bucket/my-repo `
  --admin-username alice --admin-email alice@example.com `
  --s3-access-key-id KEY_ID `
  --s3-secret-access-key SECRET_KEY `
  --s3-region REGION

This writes the repository metadata into the bucket, creating a complete FlexVault repository that workspaces can connect to.

Create your first workspace

A repository is where published history lives; you do your actual work in a workspace on your machine. Create one with fxv init, pointing it at the same s3:// URI and passing the storage flags:

fxv init s3://my-bucket/my-repo --path ./my-workspace \
  --s3-access-key-id KEY_ID \
  --s3-secret-access-key SECRET_KEY \
  --s3-region REGION

fxv init s3://my-bucket/my-repo --path ./my-workspace `
  --s3-access-key-id KEY_ID `
  --s3-secret-access-key SECRET_KEY `
  --s3-region REGION

Credentials are stored locally

FlexVault saves the storage endpoint and credentials in the workspace configuration on your machine in plain text. Treat the workspace directory as sensitive, and do not commit it or share it.

Add your user and publish

The admin user seeded when you created the repository is the bootstrap identity. The user you work as day to day can be different, so add a user for yourself, then log in as that user. Run these commands from inside the workspace directory:

cd my-workspace
fxv user add bob --email [email protected]
fxv login bob

fxv user add adds you to the repository user database, and fxv login records that your changes should be attributed to that user. Publishing requires being logged in.

Now make a change, snapshot it to a draft revision, and publish it:

echo "# My Project" > README.md
fxv snapshot --description "Add README"
fxv publish --description "First publish"

"# My Project" | Out-File -Encoding utf8 README.md
fxv snapshot --description "Add README"
fxv publish --description "First publish"

fxv snapshot records your local changes as a draft, and fxv publish promotes your current draft to a published revision in the repository, visible to everyone else connected to it.

Sync changes from other users

When another team member wants to collaborate on the repository, they install fxv and initialize their own workspace pointing at the same s3:// URI:

fxv init s3://my-bucket/my-repo --path ./their-workspace \
  --s3-access-key-id KEY_ID \
  --s3-secret-access-key SECRET_KEY \
  --s3-region REGION

fxv init s3://my-bucket/my-repo --path ./their-workspace `
  --s3-access-key-id KEY_ID `
  --s3-secret-access-key SECRET_KEY `
  --s3-region REGION

After creating a user and logging in, work flows bidirectionally. Teammates pull new published revisions into their workspace with fxv sync:

fxv sync

fxv sync pulls the latest published revision of the current branch. If that user has unpublished local draft revisions, FlexVault automatically rebases their drafts on top of incoming work. If any changes conflict, sync marks those files so you can settle them with fxv resolve. Run fxv status at any time to inspect your workspace state.

Where to next