Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vers.sh/llms.txt

Use this file to discover all available pages before exploring further.

A repository is a named scope for commits and their tags. Where vers tag gives you a flat global namespace, vers repo lets you group related commits (e.g. a whole application) with tags scoped to that group (my-app:latest, my-app:v1.2). Repos can be public or private. Public repos can be forked by other organizations, which is how you share base images.

​
Synopsis

vers repo create <name> [-d "..."]
vers repo list [-q | --format json]
vers repo get <name> [--format json]
vers repo delete <name> [<name>...]
vers repo fork <org>/<repo>:<tag> [--repo-name N] [--tag-name T]
vers repo visibility <name> --public                  # or --public=false
vers repo tag {create, list, get, update, delete} ...

​
Subcommands

​
vers repo create

Naming rules: alphanumeric plus -, _, .; 1–64 characters. Unique within your organization.
OptionDescription
-d, --descriptionOptional description
vers repo create my-app
vers repo create my-app -d "Customer-facing web app"

​
vers repo list

List repositories in your organization.
OptionDescription
-q, --quietJust names, one per line
--format jsonMachine-readable
vers repo list
vers repo list -q
vers repo list --format json | jq '.[].name'

​
vers repo get

Show details (owner, visibility, tag count, timestamps) for one repo. 
vers repo get my-app
vers repo get my-app --format json

​
vers repo delete

Delete one or more repositories. All tags in the repos are deleted too; the underlying commits are not touched. 
vers repo delete my-app
vers repo delete staging preview
vers repo delete $(vers repo list -q)   # nuke all repos

​
vers repo fork

Fork a public repository into your organization. The fork:
  1. Materializes a VM from the source tag’s commit,
  2. Re-commits it under your org,
  3. Creates a new repo + tag pointing at that commit.
OptionDescription
--repo-nameName for the forked repo (default: source repo name)
--tag-nameTag in the new repo (default: source tag name)
vers repo fork acme/ubuntu:latest
vers repo fork acme/ubuntu:latest --repo-name my-ubuntu --tag-name v1

​
vers repo visibility

Toggle a repository between public and private.
OptionDescription
--publicSet public (use --public=false for private)
vers repo visibility my-app --public
vers repo visibility my-app --public=false

​
vers repo tag

Tags scoped to a single repository. Same verbs as top-level vers tag, but qualified by --repo. 
vers repo tag create my-app latest <commit-id>
vers repo tag list my-app
vers repo tag get my-app latest
vers repo tag update my-app latest --commit <new-commit>
vers repo tag delete my-app preview

​
When to use repos vs plain tags

Plain tags

Flat, org-wide namespace. Best for a handful of long-lived names (production, staging) that don’t belong to any one application.

Repos + repo tags

Structured namespace. Best for versioned artifacts where the same tag name (latest, v1) is meaningful across many different things (my-api:latest, my-worker:latest).

​
Examples

​
Publish a base image

# Build and tag
vers build -t my-ubuntu:v1 .

# Promote the commit into a repository and make it public
COMMIT=$(vers tag get my-ubuntu:v1 --format json | jq -r '.commit_id')
vers repo create my-ubuntu -d "Ubuntu 22.04 + our dev tools"
vers repo tag create my-ubuntu v1 "$COMMIT"
vers repo visibility my-ubuntu --public
Other orgs can now consume it: 
vers repo fork yourorg/my-ubuntu:v1

​
Multi-environment promotion

COMMIT=$(vers build -q .)

vers repo tag update my-app staging --commit "$COMMIT"
# ...testing...
vers repo tag update my-app production --commit "$COMMIT"

​
Common Patterns

​
Publish a base image and let others fork it

vers build -t my-ubuntu:v1 .
COMMIT=$(vers tag get my-ubuntu:v1 --format json | jq -r .commit_id)

vers repo create my-ubuntu -d "Ubuntu 22.04 + our dev tools"
vers repo tag create my-ubuntu v1 "$COMMIT"
vers repo visibility my-ubuntu --public

​
Promote a commit through environments

COMMIT=$(vers build -q .)
vers repo tag update my-app staging    --commit "$COMMIT"
# ...after staging tests pass...
vers repo tag update my-app production --commit "$COMMIT"

​
Fork and build on top

vers repo fork acme/ubuntu:latest --repo-name my-ubuntu --tag-name v1
vers build -t my-ubuntu:v1.1 -f extend.Dockerfile .

​
Bulk cleanup of test repos

vers repo delete $(vers repo list -q | grep '^test-')

​
See also

  • vers tag — flat, org-wide tags
  • vers build — produce the commits a repo holds
  • vers deploy — deploy from a GitHub repository (different concept: source code, not commits)