@rafay99/cvx 0.18.0 → 0.24.0

package/README.md

@@ -134,16 +134,62 @@ 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 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 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` | Show the active account and this dir's link |
+| `cvx status [--json]` | Show the active account and this dir's link |
 | `cvx accounts` | List stored accounts |
 | `cvx ls` | List linked projects |
 | `cvx which [path]` | Print the account name for a dir (scripting) |
-| `cvx doctor` | Check your setup (node/npx, login, vault, hook) |
-| `cvx rm <account>` | Forget an account and its links |
-| `cvx hook [--install]` | Print (or install) the zsh cd-hook |
+| `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 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) |
+
+### Run a command as another account, without switching
+
+```sh
+cvx run work -- npx convex logs        # from anywhere, as the "work" account
+cvx run . -- npx convex deploy         # "." = this directory's linked account
+```
+
+`cvx run` sets `CONVEX_OVERRIDE_ACCESS_TOKEN` for that one process only — it never
+touches your global login, so it's safe in scripts and alongside running dev servers.
+
+### Store tokens in the OS keychain (optional)
+
+By default tokens live in `~/.convex-switch/` (chmod 600). To move them into the
+**macOS Keychain**, **libsecret** (Linux), or **DPAPI** (Windows):
+
+```sh
+cvx keychain enable      # migrates every account into the OS keychain
+cvx keychain disable     # moves them back to the file vault
+```
+
+### Shell prompt + completions
+
+```sh
+cvx completions zsh >> ~/.zshrc         # tab-complete commands + account names
+# starship: show the active account in your prompt
+# [custom.cvx]  command = "cvx prompt"  when = "true"  format = "[($output )]($style)"
+```
+
+## Upgrading from an older version
+
+The vault is schema-versioned. The first time you run an interactive `cvx`
+command after updating from an older release, cvx shows a one-time prompt and,
+on confirmation, re-secures your tokens in the best available backend (OS
+keychain if present, otherwise the chmod-600 file vault) and upgrades the vault
+format. It's mandatory and runs once — you never see it again. The cd-hook and
+scripts keep working throughout; the prompt only appears in an interactive
+terminal.
 
 ## Project layout
 

package/cvx.1

@@ -28,6 +28,9 @@ is verified against Convex; if \fIname\fR is omitted the team slug is used.
 .B cvx login \fIname\fR
 Force a fresh browser sign-in (\fBconvex login --force\fR), then store it as
 \fIname\fR. Use this to add a second or third account.
+.TP
+.B cvx refresh \fIaccount\fR
+Re-authenticate an existing account and refresh its stored token.
 .SS Wire projects to accounts
 .TP
 .B cvx link \fIaccount\fR \fR[\fIpath\fR]
@@ -37,19 +40,40 @@ account may be linked to many projects.
 .B cvx unlink \fR[\fIpath\fR]
 Remove a link.
 .TP
-.B cvx hook \fR[\fB--install\fR] [\fB--shell\fR \fIzsh\fR|\fIbash\fR|\fIpowershell\fR]
+.B cvx rename \fIold\fR \fInew\fR
+Rename an account, keeping every link that pointed at it.
+.TP
+.B cvx hook \fR[\fB--install\fR] [\fB--shell\fR \fIzsh\fR|\fIbash\fR|\fIfish\fR|\fInu\fR|\fIpowershell\fR]
 Print the directory-change hook, or with \fB--install\fR wire it into the shell
-startup file (\fI~/.zshrc\fR, \fI~/.bashrc\fR, or the PowerShell \fB$PROFILE\fR).
-The shell is auto-detected when \fB--shell\fR is omitted (PowerShell on Windows).
+startup file (\fI~/.zshrc\fR, \fI~/.bashrc\fR, fish/nushell config, or the
+PowerShell \fB$PROFILE\fR). The shell is auto-detected when \fB--shell\fR is omitted.
+.TP
+.B cvx completions \fIzsh\fR|\fIbash\fR|\fIfish\fR|\fIpowershell\fR
+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.
+.TP
+.B cvx run \fIaccount\fR \fR[\fB--\fR] \fIcommand\fR ...
+Run \fIcommand\fR with the given account active for that process only, by
+setting \fBCONVEX_OVERRIDE_ACCESS_TOKEN\fR \(em the global login is never
+touched. Use \fB.\fR as \fIaccount\fR for the current directory's linked account.
+.TP
+.B cvx open
+Open the Convex dashboard for the current project's deployment (read from
+\fI.env.local\fR), or the dashboard home if none is configured.
+.TP
 .B cvx activate \fR[\fB-q\fR] [\fIpath\fR]
 Activate the account linked to a directory by rewriting the global config. The
 shell hook calls this on every \fBcd\fR; \fB-q\fR silences the "nothing to do"
 cases.
 .TP
-.B cvx status
-Show the active account and the current directory's link.
+.B cvx status \fR[\fB--json\fR]
+Show the active account and the current directory's link. \fB--json\fR emits a
+machine-readable object for scripting.
 .TP
 .B cvx accounts
 List stored accounts; the active one is marked.
@@ -59,16 +83,25 @@ List linked projects; the current directory is marked.
 .TP
 .B cvx which \fR[\fIpath\fR]
 Print the account name for a directory (exit 1 if none). For scripting.
+.TP
+.B cvx prompt
+Print the active account name and nothing else \(em for embedding in a shell
+prompt. Fast and never errors.
 .SS Manage
 .TP
 .B cvx rm \fIaccount\fR
 Forget an account and any links pointing at it.
 .TP
-.B cvx doctor
-Check your setup and report problems: Node/npx availability (needed for
-\fBcvx login\fR), whether you have a Convex login, vault integrity, the active
-account, and whether the shell hook is installed. Exits non-zero if something
-needs attention.
+.B cvx keychain \fR[\fIstatus\fR|\fIenable\fR|\fIdisable\fR]
+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 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,
+and whether the shell hook is installed. Also pings Convex to check each stored
+token's health (skip that with \fB--no-tokens\fR). Exits non-zero on any problem.
 .TP
 .B cvx welcome
 Show the welcome screen again.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rafay99/cvx",
-  "version": "0.18.0",
+  "version": "0.24.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.js", "cvx.1", "README.md", "LICENSE"],
   "engines": { "node": ">=16" },
   "optionalDependencies": {
-    "@rafay99/cvx-darwin-arm64": "0.18.0",
-    "@rafay99/cvx-darwin-x64": "0.18.0",
-    "@rafay99/cvx-linux-x64": "0.18.0",
-    "@rafay99/cvx-linux-arm64": "0.18.0",
-    "@rafay99/cvx-win32-x64": "0.18.0"
+    "@rafay99/cvx-darwin-arm64": "0.24.0",
+    "@rafay99/cvx-darwin-x64": "0.24.0",
+    "@rafay99/cvx-linux-x64": "0.24.0",
+    "@rafay99/cvx-linux-arm64": "0.24.0",
+    "@rafay99/cvx-win32-x64": "0.24.0"
   }
 }