Skip to content
This repository was archived by the owner on Aug 13, 2026. It is now read-only.
This repository was archived by the owner on Aug 13, 2026. It is now read-only.

New command: vers publish <vm-id> <repo>:<tag>... (Docker-shaped one-liner) #202

Description

@AlephNotation

Why

Today, "publish a new version of this VM" takes a 3–4 command dance (see #201 for the breakdown). Issue #201 makes that one command via vers commit create --tag <repo>:<tag> --public. This issue is the next step: a dedicated top-level command that models the intent rather than the mechanics.

Today

vers commit create vm-123 --name v1.2 --tag my-app:v1.2 --tag my-app:latest --public

That's much better than before, but the commit create framing is still about the snapshot mechanism. The verb is "create"; the target audience is people who already know vers's data model (commits as separate first-class objects from tags).

Target

vers publish vm-123 my-app:v1.2 my-app:latest

The verb is "publish" — what you actually want to do. Positional args are the references. Behaviors:

  • Default: commit the VM with an auto-generated name + description, tag at each <repo>:<tag> reference, make commit public if any target repo is public.
  • --name/--description to override the auto-generated metadata
  • --private to opt out of auto-publish even when the repo is public
  • --json for machine output, mirroring the rest of the surface

Implementation is almost entirely composition over the primitives from #201:

vers publish vm-123 my-app:v1.2 my-app:latest
  → vers commit create vm-123 --tag my-app:v1.2 --tag my-app:latest --public

But the new command is cleaner because:

  1. No --tag flag noise. References are positional args, like docker.
  2. Verb matches intent. publish reads as a verb operation; commit create --tag reads as a noun construction.
  3. Sensible defaults. Auto-publish-when-public is the obvious default for a publish command; the conservative warn-only behavior in Add --tag (repeatable) and auto-publish to vers commit create #201 doesn't fit here.
  4. Discoverability. vers --help shows publish alongside run, branch, commit — agents and users find it by browsing the top-level surface rather than reading flag docs on commit create.

Output

{
  "vm_id": "vm-123",
  "commit_id": "...",
  "name": "auto-...",
  "is_public": true,
  "tags": [
    { "reference": "my-app:v1.2", "tag_id": "..." },
    { "reference": "my-app:latest", "tag_id": "..." }
  ]
}

Edge cases

  • No references. vers publish vm-123 with no <repo>:<tag> — error with enumerated example, or auto-generate a tag like <default-repo>:auto-<timestamp>? Recommend: error. The whole point is making a versioned reference, so requiring one is right.
  • References across multiple repos. vers publish vm-123 app-a:v1 app-b:v1 — works fine, write to both. (Unusual but valid.)
  • Repo doesn't exist. Same as Add --tag (repeatable) and auto-publish to vers commit create #201's behavior: error early with the create-it hint.
  • VM is currently HEAD. vers publish (no args) — error with enumerated reference syntax. Don't try to be clever about defaults here.

Depends on

Out of scope

  • vers.toml defaults for the project's home repo (separate concern)
  • vers publish --build to first run a build command in the VM (out of scope; user controls the VM contents)

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions