vers repo

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.

Option	Description
`-d, --description`	Optional description

vers repo create my-app
vers repo create my-app -d "Customer-facing web app"

`vers repo list`

List repositories in your organization.

Option	Description
`-q, --quiet`	Just names, one per line
`--format json`	Machine-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:

Materializes a VM from the source tag’s commit,
Re-commits it under your org,
Creates a new repo + tag pointing at that commit.

Option	Description
`--repo-name`	Name for the forked repo (default: source repo name)
`--tag-name`	Tag 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.

Option	Description
`--public`	Set 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 directly or fork it:

# Reference directly in a Dockerfile or run-commit
vers run-commit yourorg/my-ubuntu:v1

# Or fork it into your own org for local modifications
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-')

Overview

Project Commands

Branch Commands

Repository Commands

VM Commands

Environment

Auth Commands

Utility Commands

Synopsis

Subcommands

`vers repo create`

`vers repo list`

`vers repo get`

`vers repo delete`

`vers repo fork`

`vers repo visibility`

`vers repo tag`

When to use repos vs plain tags

Plain tags

Repos + repo tags

Examples

Publish a base image

Multi-environment promotion

Common Patterns

Publish a base image and let others fork it

Promote a commit through environments

Fork and build on top

Bulk cleanup of test repos

See also

​Synopsis

​Subcommands

​vers repo create

​vers repo list

​vers repo get

​vers repo delete

​vers repo fork

​vers repo visibility

​vers repo tag

​When to use repos vs plain tags

Plain tags

Repos + repo tags

​Examples

​Publish a base image

​Multi-environment promotion

​Common Patterns

​Publish a base image and let others fork it

​Promote a commit through environments

​Fork and build on top

​Bulk cleanup of test repos

​See also

Synopsis

Subcommands

`vers repo create`

`vers repo list`

`vers repo get`

`vers repo delete`

`vers repo fork`

`vers repo visibility`

`vers repo tag`

When to use repos vs plain tags

Examples

Publish a base image

Multi-environment promotion

Common Patterns

Publish a base image and let others fork it

Promote a commit through environments

Fork and build on top

Bulk cleanup of test repos

See also