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. See Repository and workspace are separate places if those two terms are new to you.

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. This is expected for a newly released tool and is safe to proceed past: click More info and then Run anyway.

Confirm the installation:

fxv --help

To update fxv later, run fxv upgrade. Watch the announcements channel on the FlexVault Discord for new CLI and plugin release notices.

Set up a repository

A FlexVault repository needs a place to live. For a team, that place is an S3-compatible object storage bucket, which FlexVault talks to directly using the S3 API.

Trying FlexVault out on your own?

You do not need a cloud provider at all. A repository can live on your local filesystem using a file:// URI instead, with no account or bucket to set up. See Set up a Local Filesystem Repository, then jump back here at Add your user and publish to continue the walkthrough.

The rest of this guide sets up a repository backed by object storage, using AWS S3 as an example. 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. Setting one up means creating an account with that provider if you do not already have one, which is likely to involve billing information.

Placeholders in examples

Values in capitals, such as KEY_ID, SECRET_KEY, and REGION, are placeholders to replace with your own, as are the example names alice, bob, my-bucket, my-repo, and my-workspace used throughout. 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.

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 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. --path is the directory fxv init creates and turns into your workspace, linked to that repository; ./my-workspace is a placeholder, so replace it with wherever you want that directory to be, such as ./my-game or an absolute path. You do not need to cd there first, since --path creates the directory for you; just remember a relative path like ./my-workspace is relative to wherever you run the command:

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 (alice, in the examples above) is a bootstrap identity: it exists so the repository has an initial administrator, not so you log in as it day to day. Add a separate user for yourself instead, 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 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 merges their drafts on top of the 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