Skip to content

Getting Started

This guide takes you from nothing to your first publish. You will install FlexVault, create a repository backed by object storage, connect a local workspace to it, and publish your first change.

This guide assumes you understand the base concepts of version control. If you want the mental model first, read the Introduction; otherwise you can follow along here and pick up the concepts as you go.

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.

Install FlexVault

FlexVault ships as a single self-contained executable named fxv. Download it, make it executable, and put it on your PATH.

Download URL

Release assets are published per platform, for example fxv-linux-x86_64 and fxv-macos-arm64. Replace the URLs below with the current link for your platform from fxv.dev/download.

curl -L https://fxv.dev/download/fxv-linux-x86_64 -o fxv
chmod +x fxv
mkdir -p ~/.local/bin && mv fxv ~/.local/bin/fxv

If ~/.local/bin is not already on your PATH, add it, for example by putting export PATH="$HOME/.local/bin:$PATH" in your shell profile.

Invoke-WebRequest -Uri https://fxv.dev/download/fxv-windows-x86_64.exe -OutFile fxv.exe
New-Item -ItemType Directory -Force -Path "$env:LOCALAPPDATA\Programs\fxv" | Out-Null
Move-Item -Force fxv.exe "$env:LOCALAPPDATA\Programs\fxv\fxv.exe"

Add that directory to your PATH, for example $env:PATH += ";$env:LOCALAPPDATA\Programs\fxv" for the current session, or through System Properties to make it permanent.

Confirm the install:

fxv --help

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.

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 alice@example.com \
  --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's metadata into the bucket, which now holds a complete FlexVault repository that workspaces can connect to. Using Cloudflare R2, Tigris, or Google Cloud Storage instead? The endpoint flags differ; see Set up a Remote Repository.

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 same 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 bob@example.com
fxv login bob

fxv user add adds you to the repository's 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

A repository is meant to be shared. When someone else wants to work on it, they install fxv and create their own workspace against the same s3:// URI, using the same storage flags you used above:

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

This pulls the current published state of the repository into their workspace. They add a user for themselves and log in the same way:

cd their-workspace
fxv user add carol --email carol@example.com
fxv login carol

From here, work flows in both directions. After you publish a new revision, the other user brings it into their workspace with fxv sync:

fxv sync

fxv sync pulls the latest published revision of the current branch. If that user has their own unpublished draft revisions, FlexVault rebases them on top of the incoming published revision, so their in-progress work is preserved. If any of their changes conflict with what was published, sync flags those files as conflicts to settle with fxv resolve before they can publish. Run fxv status at any time to see the current revision and any pending drafts or conflicts.

Where to next

  • Introduction explains the core model and the revision system in more depth.
  • CLI Reference documents every fxv command.
  • Glossary defines the terms used throughout the documentation.