> ## 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.

# vers repo

> Named repositories that group related commits with their own per-repo tags — a scope above plain tags.

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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`

<Info>
  **Naming rules**: alphanumeric plus `-`, `_`, `.`; 1–64 characters. Unique within your organization.
</Info>

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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         |

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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.

| Option        | Description                                          |
| ------------- | ---------------------------------------------------- |
| `--repo-name` | Name for the forked repo (default: source repo name) |
| `--tag-name`  | Tag in the new repo (default: source tag name)       |

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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) |

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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`.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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

<CardGroup cols={2}>
  <Card title="Plain tags" icon="tag">
    Flat, org-wide namespace. Best for a handful of long-lived names (`production`, `staging`) that don't belong to any one application.
  </Card>

  <Card title="Repos + repo tags" icon="folder-tree">
    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`).
  </Card>
</CardGroup>

## Examples

### Publish a base image

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# 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:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# 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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers repo delete $(vers repo list -q | grep '^test-')
```

## See also

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