voroa-cli 0.0.0-stage → 0.2.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,194 @@
-# 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.
+
+## 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.2.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"
+  }
+}