Via ships two CLIs. They have different jobs:
| CLI | Who runs it | Where it runs | Authentication |
|---|---|---|---|
vary | App owners | Workstation | Named target + cached short-lived session minted from a one-time adm_... token |
via | Host operators | The Via host itself (typically over SSH as a member of the vary group) | Host membership, not a network token |
vary app deploy cannot approve a domain. via domain approve cannot push
source. If a workflow needs both, split it into app-owner and operator steps.
| Surface | Prerequisite | How to satisfy it |
|---|---|---|
vary target ... | Named target | vary target add <name> https://<host> |
vary login | One-time admin token | via admin create <username> on the host |
vary app ... (target-scoped) | A current session for the target | vary login --target <name> --name <user> --token-stdin |
via ... | Host group membership | via install adds the running user to the vary admin/shared group; reconnect or newgrp vary after first install |
Many read commands support --json. Use it for tooling; the plain output is
for people reading a terminal.
vary)| Command | Purpose |
|---|---|
vary target add <name> <url> | Register a Via host as a named workstation target. |
vary target list | List configured targets. |
vary target show <name> | Show target metadata and server URL. |
vary target remove <name> | Forget a target and delete its cached session file. |
vary target doctor --target <name> | Diagnose target reachability, session validity, and clock skew. |
vary login --target <name> --name <user> --token-stdin | Exchange a one-time admin token for a short-lived session. |
vary logout --target <name> | Invalidate the cached session for a target. |
Sessions are stored under ~/.vary/credentials/sessions/<slug>.json with
mode 0600. The admin token is single-use; mint another with via admin create if you need a fresh one.
| Command | Purpose |
|---|---|
vary app create <name> --target <t> | Create the server-side app row and managed source repo. |
vary app deploy <name> --target <t> [--apply-manifest] [--resume] [--force-rebuild] | Push current HEAD, apply via.app.toml, and stream status to a terminal state. |
vary app rollback <name> --target <t> [--release <release-id>] | Switch back to the previous release, or to a named release, without rebuilding. |
vary app releases <name> --target <t> | List release candidates and current release. |
vary app restart <name> --target <t> | Restart the current runtime and wait for the server response. |
vary app stop <name> --target <t> | Stop the current runtime. |
vary app delete <name> --target <t> --plan [--json] | Preview whole-app decommission without mutating state. |
vary app delete <name> --target <t> --apply --confirm <name> | Request policy-allowed app decommission with typed confirmation. |
| Command | Purpose |
|---|---|
vary app status <name> --target <t> | Quick state snapshot. |
vary app inspect <name> --target <t> | Full deploy/build/runtime detail and gate history. |
vary app builds <name> --target <t> | List recent builds. |
vary app build <id> --target <t> | Build phase status, heartbeat, worker id, log availability, failure phase. |
vary app build logs <id> --target <t> --app <name> [--tail N] [--since N] [--follow] | Read or stream build logs for a specific build. |
vary app build cancel <id> --target <t> [--app <name>] [--follow] | Cancel an active, queued, or stuck build and return an operation id. |
vary app deploy retry <deploy-id> --target <t> --app <name> [--apply-manifest] [--follow] | Queue a retry for a failed or cancelled deploy and optionally follow it. |
vary app doctor <name> --target <t> | Diagnose route, runtime, dependency, build consistency, stuck-build, and log-availability problems. |
vary app repair <name> --target <t> [--dry-run] [--json] | Plan or run safe runtime health repairs such as identity renewal. |
vary app logs <name> --target <t> [--source runtime|build] [--tail N] [--since OFFSET] | Read persisted runtime or build logs. |
vary app smoke <name> --target <t> | Exercise the externally advertised route. |
vary app preflight <name> --target <t> | Readiness preflight: manifest, route gates, auth, bindings. |
vary app reconcile <name> --target <t> --apply-manifest --plan [--json] | Preview deploy-state reconciliation for stale routes, add-ons, and staged state. |
vary app debug-bundle <name> --target <t> | Write a redacted zip with status, inspect, deploy/build, logs, and target doctor data. |
| Command | Purpose |
|---|---|
vary app source show <name> --target <t> | Inspect the Via-hosted source state. |
vary app source resolve-ref <name> <ref> --target <t> | Resolve a ref to a commit on the Via-hosted Git remote. |
vary app source commits <name> --target <t> | List recent commits. |
vary app source remote <name> --target <t> | Show the authenticated Git remote URL Via accepts. |
vary app source refs <name> --target <t> | List refs on the managed bare repo. |
| Command | Purpose |
|---|---|
vary app config patch <name> --target <t> [--replicas N] [--memory-mb N] | Stage an immutable config profile version. |
vary app config validate <name> --target <t> | Validate a staged config without applying. |
vary app config diff <name> --target <t> | Diff staged vs. running config. |
vary app config redeploy <name> --target <t> | Roll out a config-only change without a new push. |
vary app config template <name> --target <t> --workdir <dir> | Render an editable config and secret template from the effective app manifest. |
vary app config apply <name> --target <t> --file <file> | Apply template values as plain config and redacted secrets. |
vary app env set <name> KEY --target <t> --value VALUE | Set or update a plain environment variable. |
vary app env set <name> KEY --target <t> --secret | Read a secret environment value from stdin or an interactive prompt. |
vary app env rotate <name> KEY --target <t> | Rotate a secret-backed env value to a new generation. |
vary app env history <name> KEY --target <t> | Redacted history of an env variable. |
| Command | Purpose |
|---|---|
vary app manifest apply <name> --target <t> [--file via.app.toml] | Apply via.app.toml to the app. |
vary app domain list <name> --target <t> | List app-scoped domain requests and approval state. |
vary app domain request <name> <hostname> --target <t> | Open or reuse an app-domain request. |
vary app domain verify <name> <hostname> --target <t> | Ask the server to verify the domain proof. |
vary app route add <name> <hostname> --target <t> [--path-prefix /] [--port N] | Create an app route for a verified hostname. |
| Command | Purpose |
|---|---|
vary job run <path-or-ref> --target <t> [--app <name>] [--arg VALUE] [--follow] | Submit a one-shot job. |
vary job cancel <id> --target <t> | Cancel a pending or running job. |
vary job logs <id> --target <t> [--tail N] [--since OFFSET] | Read job logs. |
via)These commands run on the Via host itself. They never accept a --target
flag because they always operate against the local control plane.
| Command | Purpose |
|---|---|
via install | Install Via on a fresh Ubuntu host. |
via init --domain <fqdn> | Initialize the control plane with the platform domain. |
via status | Per-component status table; --json returns a structured object. |
via doctor | Run the host check suite; non-zero on any failure. |
via admin create <username> | Mint a one-time adm_... token for a new operator. |
via admin token create <name> --scope app:deploy --ttl 2h | Mint a scoped short-lived adm_... token for session renewal without creating a permanent admin credential. |
via domain approve <app> <hostname> | Approve a policy-controlled app-domain request. |
via domain reject <app> <hostname> --reason "..." | Reject a request with an operator-visible reason. |
via load-balancer routes | Inspect the effective platform and app route table. |
via load-balancer reload | Apply valid route state through the managed proxy. |
via app build <id> / via app tests <id> | Inspect local build and test records from the control plane. |
via app reconcile <name> --plan / --apply [--approve-cleanup] | Inspect or apply operator-approved cleanup for stale app state. |
via app delete <name> --plan / --apply --confirm <name> | Decommission an app with audited plan/apply semantics and retention policy. |
via app secret set|list|rotate|delete | Manage local app secret values from the Via host. |
via route status --app <app> <host> [--json] | Inspect normalized route readiness without changing the app-owner deploy flow. |
via addon ensure sqlite <name> --app <app> --bind <binding> [--repair] [--json] | Idempotently create or verify a SQLite add-on, binding, and storage readiness. |
via addon status <name> [--json] | Inspect add-on lifecycle, binding, storage, and runtime usability readiness. |
via key rotate identity|artifacts | Rotate identity or artifact signing keys. |
via secret key rotate | Rotate the AES-256-GCM secret encryption key. |
via backup create <path> / via backup restore <path> | Operator backup and restore; --include-secrets for full bundles, --allow-checksum-drift for pre-baseline recovery backups. |
via control-plane rebaseline --from-prebaseline | Explicitly repair known-compatible pre-baseline migration metadata after backup and typed confirmation. |
via control-plane clean-install --dry-run | Preview the destructive clean-install recovery path and required typed confirmation. |
via upgrade resume | Resume the idempotent upgrade path after an interrupted promotion or rebaseline repair. |
| Asked-for command | Use instead |
|---|---|
vary server ... | vary target ... for named remote targets; via ... for host operator control. The vary server command no longer exists. |
| Remote app secret subcommands | Use vary app env ... --target <t> for app-owner secret-backed environment values, or via app secret ... on the Via host. |
Operator commands on vary | All operator commands live under the via binary. |
Standalone vary lsp-server binary | Use vary lsp from the main vary binary. |
app delete is the decommission path. It is for retired or unrecoverable app
records, not for retrying a failed deploy. The plan response lists route,
runtime, config/env, source/build/release/log/test evidence, add-on, audit,
retention, tombstone, and name-reuse effects before any mutation. Apply requires
--confirm <app>. Stateful add-ons are retained by default; use one explicit
policy flag when the operator has decided otherwise:
| Flag | Policy sent to the API |
|---|---|
| no flag | retain |
--detach-addons | detach |
--snapshot-addons | snapshot-then-destroy |
--destroy-addons | destroy |
If apply fails after route/runtime cleanup has started, the command returns
delete_partial_retryable with partial: true, a decommission_failed app
state, and a retry_command. Fix the reported blocker and run the retry
command; completed cleanup steps are idempotent.
app reconcile is for drift: stale inactive routes, failed route capability
records, stale add-on state, runtime trust bootstrap gaps, control-plane/runtime
mismatches, or inconsistent deploy evidence. Developer apply requires
--apply-manifest and performs only developer-safe cleanup, such as cancelling
non-current staged deploy state and removing developer-owned safe stale routes.
If the plan includes operator-only repair, such as platform SQLite storage
repair, runtime trust repair, runtime mismatch investigation, or active traffic
cleanup, developer apply stops with an operator escalation command. Operator
apply can repair safe host/app drift and can add --approve-cleanup for
policy-gated cleanup.
Automatic deploy and retry reconciliation writes an app_automatic_reconcile
audit event whenever it mutates stale state. The reconcile plan JSON includes
recent cleanup_history entries with audit IDs, applied counts, and operation
IDs so operators can see what automation already handled before deciding
whether manual cleanup is still needed.
For deploy retries, prefer vary app deploy retry <deploy-id> --target <t> --app <name> --apply-manifest. The manifest route keys let Via classify
current desired routes separately from historical stale routes before it queues
the replacement deploy. Active stale traffic still blocks with the operator
via app reconcile <app> --apply --approve-cleanup escalation.
The apps.delete permission covers operator whole-app decommission and
tombstone purge. App owners with app write access can request self-service
decommission only for safe retained-state cases. The target API blocks
self-service apply when deletion would disable active routes, retire
certificate-bound domains, purge tombstones, or destroy stateful add-ons. If the
app-owner vary app delete command reports an operator boundary, rerun the plan
with via app delete <app> --plan --json on the host and attach that output to
the escalation.
via addon ensure sqlite <name> --app <app> --bind <binding> --json returns
the mutation summary fields created, already_exists, changed,
compatible, and warning. via addon status <name> --json reports the same
readiness fields for an existing add-on:
metadata_ready, storage_ready, binding_ready, runtime_ready,
usable_by_app, blocking, owner, reason, and remediation.
When provider storage is missing, the blocker is reported as storage_missing
and the remediation points to via addon ensure ... --repair. A timeout after
compatible state is confirmed is surfaced as a non-fatal warning.
via route status --json, via route ready --json, and
vary app preflight --json report route readiness as separate layers:
domain_verification, certificate, load_balancer, runtime, readiness,
blocking, owner, and remediation. vary app status --json exposes the
same route readiness model for app-owned routes. If the route table says traffic
is materialized but the domain/certificate request is not ready, or vice versa,
the blocker is state_inconsistent, state_inconsistent is true, and
readiness is blocked_state_inconsistent.
Operators can use via app reconcile <app> --apply to repair safe
platform-owned route/domain/certificate drift when the active route is already
valid and materialized. The same plan reports runtime trust bootstrap gaps with
via doctor --fix as the next command, and reports control-plane/runtime
mismatches as blocked operator drift instead of treating the app as healthy.
See Deploy an app for the app-owner workflow and Operations for the operator workflow.