@rafay99/cvx 0.33.0 → 0.38.0

package/README.md

@@ -10,6 +10,19 @@ You link a project folder to an account **once**. After that, the moment you
 terminals — each grabs its own account as it launches and they all run at the
 same time.
 
+```
+  (◕‿◕)~@    happy — the right account is active
+  (⊙︵⊙)~@    alarmed — this project's team doesn't match the account
+  (–ᴗ–)ᶻ~@   asleep — the encrypted vault is locked
+  (◕‿<)~@    that's `cvx doctor` coming back clean
+```
+
+Meet **Vex**, the account chameleon. A chameleon changes color to match its
+surroundings; cvx changes your account to match your project — so Vex wears
+the **active account's color** and her face reacts to what's going on. Every
+account gets a stable color of its own, used across `accounts`, `ls`, and
+switch messages, so you learn to recognize where you are at a glance.
+
 ## Purpose
 
 The Convex CLI only remembers **one** logged-in account at a time — it lives in
@@ -117,6 +130,14 @@ cd ~/Code/project-b && cvx link work
 cd ~/Code/project-c && cvx link personal   # one account → many projects
 ```
 
+## Safety net: the wrong-account guard
+
+The Convex CLI stamps a `# team: …` note on the `CONVEX_DEPLOYMENT` line of
+`.env.local`. On every activation (including the automatic cd-hook), cvx
+cross-checks that team against the linked account's teams and warns loudly on
+a mismatch — catching "about to deploy with the wrong account" *before* it
+happens. `cvx status` shows the same warning.
+
 ## Daily use
 
 ```bash
@@ -134,21 +155,24 @@ bun run dev             # runs as work — both live simultaneously
 | --- | --- |
 | `cvx add [name]` | Store the current `~/.convex` login as an account |
 | `cvx login <name>` | `npx convex login`, then store it as `<name>` |
-| `cvx refresh <account>` | Re-authenticate an account (refresh its token) |
+| `cvx refresh <account>` / `--all` | Re-authenticate one account — or every account in one sitting |
 | `cvx link <account> [path]` | Link a project dir (default cwd) to an account |
 | `cvx unlink [path]` | Remove a link |
 | `cvx rename <old> <new>` | Rename an account, keeping its links |
 | `cvx rm <account>` | Forget an account and its links |
-| `cvx use` | Activate this dir's account — or pick one interactively if unlinked |
+| `cvx use [account]` | Activate by name from anywhere — or this dir's account / an interactive pick |
 | `cvx run <account> -- <cmd>` | Run one command as `<account>` without changing the global login |
 | `cvx open` | Open the Convex dashboard for this project's deployment |
 | `cvx activate [-q]` | Activate this dir's account (the hook calls this) |
 | `cvx status [--json]` | Show the active account and this dir's link |
-| `cvx accounts` | List stored accounts |
+| `cvx accounts` | List stored accounts (with when each token was last verified) |
 | `cvx ls` | List linked projects |
 | `cvx which [path]` | Print the account name for a dir (scripting) |
 | `cvx prompt` | Print the active account name (for a shell prompt segment) |
 | `cvx keychain <status\|enable\|disable>` | Store tokens in the OS keychain instead of a file |
+| `cvx vault <status\|encrypt\|decrypt\|unlock\|lock>` | Passphrase-encrypt stored tokens (unlock once per session) |
+| `cvx export [file]` / `cvx import <file>` | Encrypted vault backup / restore — new-machine setup in one command |
+| `cvx upgrade` | Check for a newer release and print the exact upgrade command |
 | `cvx doctor` | Check setup + per-account token health |
 | `cvx completions <shell>` | Print a completion script (zsh/bash/fish/powershell) |
 | `cvx hook [--install] [--shell …]` | Install the cd-hook (zsh/bash/fish/nu/powershell) |
@@ -199,11 +223,18 @@ a single binary, so the split costs nothing at build time.
 
 ```
 bin/cvx.ts        entry point + command dispatch
-src/store.ts      data layer: vault I/O, the config swap, token verify, paths
-src/ui.ts         the logo banner, first-run welcome, help
-src/colors.ts     the palette (edit here to re-theme)
+src/paths.ts      the ONE place HOME is resolved (CVX_HOME sandbox support)
+src/store.ts      data layer: vault I/O, the config swap, token verify
+src/ui.ts         the gradient logo, Vex the mascot, welcome, help
+src/colors.ts     the palette: brand gradient + per-account colors (re-theme here)
+src/spinner.ts    braille spinner for network waits (TTY only)
 src/commands.ts   one function per subcommand
 src/hooks.ts      zsh / bash / PowerShell shell-hook snippets
+src/keychain.ts   OS keychain / DPAPI token backends
+src/crypto.ts     scrypt + AES-256-GCM (vault encryption, export files)
+src/vault.ts      passphrase-encrypted vault + session unlock
+src/transfer.ts   cvx export / import (encrypted backups)
+src/upgrade.ts    cvx upgrade (release check)
 src/system.ts     external-tool checks (node/npx)
 src/args.ts       flag parsing
 man/cvx.1         man page (installed by Homebrew/npm → `man cvx`)

package/cvx.1

@@ -52,10 +52,12 @@ PowerShell \fB$PROFILE\fR). The shell is auto-detected when \fB--shell\fR is omi
 Print a shell completion script (completes commands and account names).
 .SS Everyday
 .TP
-.B cvx use \fR[\fIpath\fR]
-Activate the account linked to a directory. If the directory isn't linked and
-the terminal is interactive, pick an account from a list (uses \fBfzf\fR if
-installed) and optionally link the directory.
+.B cvx use \fR[\fIaccount\fR|\fIpath\fR]
+With an account name: activate that account globally, from anywhere. With a
+path (or nothing): activate the directory's linked account; if unlinked and
+the terminal is interactive, pick from a list (uses \fBfzf\fR if installed)
+and optionally link the directory. A name wins over a same-named directory
+\(em use \fI./dir\fR to force the path meaning.
 .TP
 .B cvx run \fIaccount\fR \fR[\fB--\fR] \fIcommand\fR ...
 Run \fIcommand\fR with the given account active for that process only, by
@@ -97,6 +99,24 @@ Show or change where account tokens are stored. \fBenable\fR moves them into the
 OS keychain (macOS Keychain, libsecret on Linux, DPAPI on Windows); \fBdisable\fR
 moves them back to the chmod-600 file vault.
 .TP
+.B cvx vault \fR<\fBstatus\fR|\fBencrypt\fR|\fBdecrypt\fR|\fBunlock\fR|\fBlock\fR>
+Passphrase-encrypt the stored tokens (AES-256-GCM, scrypt-derived key).
+\fBunlock\fR caches the key for the session (cleared by \fBlock\fR or a
+reboot); while locked, tokens are unreadable and commands point at
+\fBcvx vault unlock\fR. Scripts can set \fBCVX_PASSPHRASE\fR instead.
+.TP
+.B cvx export \fR[\fIfile\fR] / \fBcvx import \fR\fIfile\fR [\fB--force\fR]
+Write a passphrase-encrypted backup of the vault (accounts + links), and
+restore it on another machine. Import merges; existing names are kept unless
+\fB--force\fR.
+.TP
+.B cvx refresh --all
+Re-authenticate every stored account in one sitting (a browser sign-in each).
+.TP
+.B cvx upgrade
+Check for a newer cvx release and print the exact upgrade command for how it
+was installed (Homebrew, npm/bun, or GitHub tarball).
+.TP
 .B cvx doctor \fR[\fB--no-tokens\fR]
 Check your setup and report problems: Node/npx availability, whether you have a
 Convex login, vault integrity, the token storage backend, the active account,
@@ -125,6 +145,13 @@ The Convex CLI's global login, which \fBcvx\fR rewrites.
 .TP
 .B NO_COLOR
 Disable colored output.
+.TP
+.B CVX_HOME
+Relocate everything cvx touches (vault, global Convex config, hook rc files)
+under this directory \(em a fully isolated sandbox for testing.
+.TP
+.B CVX_PASSPHRASE
+Non-interactive passphrase for \fBcvx vault\fR and \fBcvx export\fR/\fBimport\fR.
 .SH EXAMPLES
 .PP
 Add two accounts and wire up projects:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rafay99/cvx",
-  "version": "0.33.0",
+  "version": "0.38.0",
   "description": "Switch Convex accounts per project automatically — run many Convex accounts across projects at once, no login/logout churn, no deploy keys, no tokens in your repos",
   "keywords": [
     "convex", "convex-dev", "convex-cli", "cli", "command-line",
@@ -19,10 +19,10 @@
   "files": ["launcher.cjs", "cvx.1", "README.md", "LICENSE"],
   "engines": { "node": ">=16" },
   "optionalDependencies": {
-    "@rafay99/cvx-darwin-arm64": "0.33.0",
-    "@rafay99/cvx-darwin-x64": "0.33.0",
-    "@rafay99/cvx-linux-x64": "0.33.0",
-    "@rafay99/cvx-linux-arm64": "0.33.0",
-    "@rafay99/cvx-win32-x64": "0.33.0"
+    "@rafay99/cvx-darwin-arm64": "0.38.0",
+    "@rafay99/cvx-darwin-x64": "0.38.0",
+    "@rafay99/cvx-linux-x64": "0.38.0",
+    "@rafay99/cvx-linux-arm64": "0.38.0",
+    "@rafay99/cvx-win32-x64": "0.38.0"
   }
 }