Skip to content

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

@AlephNotation

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
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions