voroa-cli 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Web Tech Digital Work
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,248 @@
-# Temporary Holding Version
+# voroa-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<!--
+ZERO RUNTIME DEPENDENCIES - and that is a decision, not an oversight.
+
+This package installs onto machines we do not control: a laptop, a CI image, a colleague's
+Windows box. Two entries in the project's known-bugs log are exactly that failure mode:
+
+  bug #2  - `npm install` died building a native module (node-gyp / "could not find Visual
+            Studio") because the installed Node had no prebuilt binary for it.
+  bug #11 - the same package fell back to compiling from source inside a slim Docker image
+            that had no Python and no build tools, so the image would not build at all.
+
+A CLI that cannot be installed is worse than a CLI that is missing a nicety. So: no native
+modules, no node-gyp, no prebuild-install, and no transitive supply chain to audit. HTTP is
+the built-in `fetch`, prompts are `node:readline`, tests are `node --test`. Node >=20 gives
+us all three in the standard library.
+
+If a future change wants a dependency, the bar is that question again: what happens on the
+machine where it does not compile?
+
+PUBLISHING: released through .github/workflows/publish-cli.yml (manual trigger, dry-run by default, npm
+trusted publishing - no stored token). The docs pages `docs-site/content/cli.md` and `cli-reference.md`
+flip from `status: coming-soon` only AFTER `npm view voroa-cli` resolves, never before (coming-soon
+honesty: we do not describe something a reader cannot get).
+-->
+
+Deploy and inspect Voroa services from the terminal.
+
+## Install
+
+Needs Node 20 or newer.
+
+```
+npm install -g voroa-cli
+voroa --help
+```
+
+Or without installing: `npx voroa-cli --help`.
+
+## Sign in
+
+```
+voroa login              # emails you a 6-digit code
+voroa login --password   # email + password instead
+```
+
+The session token is written to `~/.voroa/config.json` with owner-only permissions (`0600`
+on Linux and macOS; on Windows the file inherits your user profile's ACL, which the Node
+runtime cannot narrow further). The token is never printed, never passed on a command line
+and never included in an error message.
+
+**A stored session is bound to the endpoint that issued it.** If you point the CLI somewhere
+else with `--api-url` or `VOROA_API_URL`, the stored token is deliberately *not* sent there
+and the command stops with a message naming the endpoint your session belongs to. That flag
+is one word in a command you might paste from anywhere, and a live session token is not
+something to hand to whatever host it names. To use a different endpoint, sign in to it
+(`voroa login --api-url <url>`) or pass `VOROA_TOKEN` explicitly.
+
+For CI, set `VOROA_TOKEN` instead of signing in — it is an explicit choice by whoever runs
+the command, so it works against any endpoint. Use an **API token** created in the dashboard
+(it starts with `voroa_cat_`): it is scoped, revocable, expires, and is pinned to one workspace,
+so `--workspace` does not apply to it. A login session in a CI secret is a full-power login with
+none of those limits. A token reaches only what its scopes allow; a command outside them fails
+with "not available to an API token". Live build streaming is session-only, so
+`deploy --wait` with a token polls instead. `VOROA_API_URL` overrides the API endpoint
+(so does `--api-url`, which is mainly useful against a local backend).
+
+Signing in as a different account clears the workspace you had selected, so a workspace id
+from one account is never sent on another's behalf.
+
+## Commands
+
+```
+voroa services                      list the services in the active workspace
+voroa status <service>              one service's live state
+voroa logs <service>                tail the running container's output
+voroa logs <service> --follow       keep tailing
+voroa logs <service> --build        the latest build's log (add a deploy id for an older one)
+voroa deploy <service>              trigger a deploy
+voroa deploy <service> --wait       trigger a deploy and wait for the outcome
+voroa deploy <service> --follow     also stream the build log while it waits
+voroa restart|stop|start <service>  restart, stop or start the running service
+voroa rollback <service> [--to <id>] serve the previous version, or a chosen deploy, again
+voroa env list [service]            variable names
+voroa env set <KEY> [service]       value from stdin or a hidden prompt; --overwrite to replace
+voroa env unset <KEY> [service]     remove a variable
+voroa db list                       databases in the active workspace
+voroa db connect <database>         open psql as the postgres user (asks you to confirm it is you)
+voroa tokens list                    API tokens
+voroa tokens create --name <n> --scope <a,b>   the value is shown once
+voroa tokens revoke <id>            stop a token working immediately
+voroa domains list [service]        custom domains and their state
+voroa domains add <domain>          add one and print the DNS record to create
+voroa domains verify <domain>       check it (exit 2 until live; --fix re-applies a stuck one)
+voroa ssh [service] [--print]       a shell in the running service (uses your account's SSH keys)
+voroa link <service>                bind this folder to a service
+voroa unlink                        remove that binding
+voroa open [service] [--print]      the service's dashboard page
+voroa workspace list                your workspaces
+voroa workspace set <id>            choose the workspace later commands act on
+```
+
+`<service>` is a service name or its id. Names are resolved only within the active
+workspace; if two services share a name you will be asked for the id.
+
+`voroa link` writes `.voroa.json` (a service id, its name and the workspace id - no secret, safe
+to commit). In that folder and any subfolder, `<service>` becomes optional. The id is checked
+against your workspace on every command, so a link copied from someone else's repository does
+nothing. An explicit `--workspace` still wins over the one the link remembers.
+
+## Interactive session
+
+Run `voroa` with nothing after it and you get a session instead of a single command:
+
+```
+$ voroa
+
+  | ^ voroa  CLI 0.3.0
+  |
+  | Account   you@example.com
+  | Services  * 2 running   o 1 idle   x 0 failed
+
+  /help commands  -  Tab complete  -  Ctrl+C stop  -  /exit
+
+voroa > services
+voroa > logs web --follow
+voroa > deploy web --wait
+voroa > /exit
+```
+
+Every command on this page works there, with or without the leading `/`. **Tab** completes a command
+name, then a service name. **Up arrow** recalls earlier commands - only commands: what you type into a
+password, code or value prompt is never kept. **Ctrl+C** stops a running log tail and returns to the
+prompt; at an empty prompt, pressing it twice leaves, as does `/exit` or Ctrl+D. A command that fails
+prints its message and the session carries on.
+
+It is not a shell: quotes group words (`--command "node job.js"`), and nothing else on the line is
+expanded or executed. In a pipe or in CI, `voroa` with no arguments prints the usage text exactly as
+before; `voroa session` opens a session by name.
+
+On a real terminal the header, the status marks (green running, grey idle, amber changing, red failed)
+and the last line of a deploy are coloured. That is decoration on top of the words: set `NO_COLOR`, or
+pipe the output anywhere, and you get the same text with no colour and no escape codes.
+
+## For scripts and AI agents
+
+```
+voroa agent            the rules, written for a model to read
+voroa agent --json     the same as data
+```
+
+- `--json` on any command: the result is JSON on stdout, and a failure is one object on stderr,
+  `{"error": "...", "code": "NOT_FOUND"}`. The codes are a short fixed list - `voroa agent` prints them.
+- `--no-input` or `VOROA_NO_INPUT=1`: a step that would ask a question (a sign-in code, a password)
+  fails at once with `NEEDS_HUMAN` instead of waiting for an answer nobody will type.
+- `deploy --wait --json` prints one object when it ends, with `outcome` (`live`, `failed`,
+  `failed_to_start`, `timeout`, ...) and the same `exitCode` the process returns.
+- `logs --json` prints `{"service", "lines"}`; with `--follow`, one `{"line"}` object per line.
+- `status --all --json` gives every service with its `verdict` in one call.
+- `voroa tools <word>` narrows the list (`voroa tools bucket`); each command is marked as changing
+  something or not.
+- A flag a command does not have is refused (`BAD_INPUT`), never ignored.
+- Authenticate an agent with `VOROA_TOKEN`, never with a sign-in.
+
+## Everything else: `voroa tools`
+
+The commands above are the everyday ones. Everything else the platform lets a token do is a command
+too - projects and environments, scheduled tasks, database backups and users, storage buckets,
+environment groups, previews, edge cache, maintenance mode, usage, invoices, support tickets:
+
+```
+voroa tools                          the full list, one line each
+voroa list-buckets                   run one
+voroa create-scheduled-task --help   what it takes
+voroa create-scheduled-task web --name nightly --command "node job.js" --frequency daily
+voroa get-database-metrics <database-id> --json
+voroa tool restart web               one whose short name an everyday command already uses
+```
+
+These are the same operations, with the same checks and the same output, that the Voroa connector
+for AI clients offers - the CLI runs that tool set directly, so the two cannot drift apart.
+
+- **Arguments** are flags named after the argument (`--service-id`, `--database-id`). Required ones
+  can also be given as bare words, in the order `--help` lists them. `--args '<json>'` or
+  `--args-file <path>` passes them all as one JSON object.
+- **Keep secrets off the command line.** A flag's value lands in your shell history. When an argument
+  is a secret - a variable's value, a secret file's contents - put the arguments in a file, or pipe
+  them: `cat vars.json | voroa set-env-vars --args-file -`.
+- **A service** can be given by name, and can be left out in a folder you have run `voroa link` in.
+  Databases, buckets and the rest are given by id - the matching `list-...` command prints it.
+- **Output** is a table for a simple list and JSON otherwise. `--json` is always JSON.
+- **They need an API token**, not just a sign-in. Either set `VOROA_TOKEN`, or create one and keep it
+  on this machine:
+
+  ```
+  voroa tokens create --name cli --scope services:read,services:act,services:write,services:admin --save
+  ```
+
+  With `--save` the value is stored in `~/.voroa/config.json` and never printed. A token expires
+  (90 days, or 30 when it carries `services:admin`); when it does, run the same command again.
+- **Creating or deleting a resource is proposed, not done.** `voroa propose --action create_bucket
+  --args '{...}'` raises a request that a person approves in the dashboard. Nothing irreversible
+  happens from the terminal, and no command here can move money or read a secret's value.
+
+## Environment variables
+
+Values are write-only: they can be set or replaced, never shown or downloaded, so there is no
+`env pull`. A value is never taken from the command line (it would land in shell history) - pipe
+it in: `echo "$DATABASE_URL" | voroa env set DATABASE_URL`. Replacing an existing key needs
+`--overwrite`, because the old value is gone for good. Setting or removing a variable redeploys.
+
+## Confirming it is you
+
+Revealing a database password and creating an API token need a fresh confirmation on top of
+being signed in. The CLI asks only when Voroa asks for it: your authenticator code (or a recovery
+code with `--recovery`) if two-step verification is on, otherwise your password or an emailed
+code. A passkey cannot be used from a terminal. `voroa login` completes two-step sign-in the same
+way. `db connect` hands the password to psql through its environment, never the command line, and
+prints it only with `--show-url`.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | The command succeeded. With `deploy --wait`, the service is live. |
+| 1 | The command failed - including a deploy that failed or failed to start. |
+| 2 | `deploy --wait` ran out of time while the deploy was still going. |
+
+Code 2 is deliberately not 0. A timeout means we stopped watching, not that the deploy
+worked.
+
+## Global flags
+
+```
+--workspace <id>   act on this workspace for this command only
+--api-url <url>    talk to a different Voroa API
+--json             machine-readable output (services, status, workspace list)
+--lines <n>        with logs: how many lines to fetch (default 100, maximum 1000)
+--search <text>    with logs: only lines containing the text, ignoring case (last 24 hours)
+--timeout <min>    with deploy --wait: how long to wait (default 10)
+--help, --version
+```
+
+`--lines` and `--timeout` take a number. A value that is not one is refused rather than
+quietly replaced by the default — `--timeout abc` used to wait ten minutes without saying so.
+`--lines` above the server's maximum of 1000 is clamped to it, because that ceiling is
+published and clamping is what it means.

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "voroa-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Voroa command line interface - deploy, inspect and manage your services, databases, cron jobs and storage from the terminal.",
+  "type": "module",
+  "license": "MIT",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/srtayde94/voroa.git",
+    "directory": "cli"
+  },
+  "bin": {
+    "voroa": "src/index.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "prepack": "node scripts/pack-mcp.mjs",
+    "postpack": "node scripts/pack-mcp.mjs --clean"
+  },
+  "keywords": [
+    "voroa",
+    "cli",
+    "paas",
+    "deploy",
+    "logs"
+  ],
+  "homepage": "https://getvoroa.com/docs/cli",
+  "bugs": {
+    "url": "https://getvoroa.com/docs/cli",
+    "email": "support@getvoroa.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/agent.js

@@ -0,0 +1,95 @@
+// `voroa agent` - how to drive this CLI, written for an AI agent to read.
+//
+// A customer's coding agent (Claude Code, Cursor, anything that can run a shell command) does not need
+// a plugin to use Voroa: it needs to know five rules and where to look things up. This prints them.
+// The exit codes and error codes are READ from the modules that own them, not retyped, so the guide
+// cannot describe a contract the binary does not keep (test/agent.test.js).
+import { ERROR_CODES } from './errors.js';
+import { EXIT_OK, EXIT_FAILED, EXIT_TIMEOUT, VERDICT_MEANINGS } from './status.js';
+import { out, json } from './output.js';
+
+const EXIT_CODES = {
+  [EXIT_OK]: 'Succeeded. With deploy --wait: the service is live.',
+  [EXIT_FAILED]: 'Failed. The error says why.',
+  [EXIT_TIMEOUT]: 'Still going when the wait ended (deploy --wait), or not live yet (domains verify). Not a failure and not a success - check again.',
+};
+
+const RULES = [
+  'Authenticate with the VOROA_TOKEN environment variable: an API token that starts with voroa_cat_. A person creates it (dashboard: Settings -> API tokens, or `voroa tokens create`). You cannot sign in yourself - `voroa login` sends a code to a person\'s email.',
+  'Add --json to every command. The result is JSON on stdout. A failure is one JSON object on stderr: {"error": "...", "code": "..."}.',
+  'Set VOROA_NO_INPUT=1 (or pass --no-input). A step that needs a person then fails at once with code NEEDS_HUMAN instead of waiting for an answer that will not come.',
+  'Read the exit code, not the text. It says whether the COMMAND worked - not whether a service is healthy: `voroa status` exits 0 for a stopped service too. For health, read the "verdict" field (table below), never the raw "status" field.',
+  'Prefer the everyday commands (services, status, logs, deploy, restart, rollback, env, domains). The `voroa tools` commands cover everything else; a few overlap (services and list-services are the same list).',
+  'To stay read-only, run only commands that `voroa tools` marks "changes: no", plus services, status and logs.',
+  'A service is named by its name or its id. Every other resource (database, bucket, task) takes an id - get it from the matching list command.',
+  'Creating or deleting a resource is a PROPOSAL: `voroa propose` returns a request a person approves in the dashboard. Tell the person; do not retry, and do not look for another way.',
+  'Never put a secret value in a command line. Pipe it: `printf %s "$VALUE" | voroa env set KEY <service>`, or pass arguments with --args-file.',
+];
+
+const DISCOVER = [
+  ['voroa tools <word> --json', 'platform commands matching a word (bucket, backup, task...), each with its argument schema and whether it changes anything'],
+  ['voroa tools --json', 'all of them (large)'],
+  ['voroa <tools-command> --help', 'one of those: what it does and what it takes'],
+  ['voroa --help', 'the everyday commands and their flags'],
+  ['voroa agent --json', 'this guide as data'],
+];
+
+const EXAMPLES = [
+  ['voroa services --json', 'the services (names, ids, repository, branch)'],
+  ['voroa status --all --json', 'how every service is doing: its verdict'],
+  ['voroa status <service> --json', 'one service in full'],
+  ['voroa deploy <service> --wait --json', 'deploy and wait; exit 0 only when live'],
+  ['voroa logs <service> --lines 100 --json', 'recent output'],
+  ['voroa get-deploy-history <service> --json', 'what was deployed, and how it went'],
+  ['voroa rollback <service> --json', 'serve the previous version again'],
+];
+
+export function agentGuide(version) {
+  return {
+    cli: 'voroa',
+    version,
+    rules: RULES,
+    exitCodes: EXIT_CODES,
+    errorCodes: ERROR_CODES,
+    verdicts: VERDICT_MEANINGS,
+    discover: DISCOVER.map(([command, what]) => ({ command, what })),
+    examples: EXAMPLES.map(([command, what]) => ({ command, what })),
+  };
+}
+
+const table = (rows) => {
+  const width = Math.max(...rows.map(([a]) => String(a).length));
+  return rows.map(([a, b]) => `  ${String(a).padEnd(width)}  ${b}`).join('\n');
+};
+
+export function agent({ flags, version }) {
+  const guide = agentGuide(version);
+  if (flags.json) {
+    json(guide);
+    return 0;
+  }
+  out(
+    [
+      `Voroa CLI ${version} - guide for an AI agent`,
+      '',
+      'Rules',
+      ...RULES.map((r, i) => `  ${i + 1}. ${r}`),
+      '',
+      'Exit codes',
+      table(Object.entries(EXIT_CODES)),
+      '',
+      'Error codes (the "code" field of a --json failure)',
+      table(Object.entries(ERROR_CODES)),
+      '',
+      'A service\'s "verdict"',
+      table(Object.entries(VERDICT_MEANINGS)),
+      '',
+      'Look things up',
+      table(DISCOVER),
+      '',
+      'Examples',
+      table(EXAMPLES),
+    ].join('\n')
+  );
+  return 0;
+}