CLI Reference

Install the CLI as a development dependency:

npm install --save-dev @gonvex/cli

The package exposes the gonvex binary. The current CLI implements account login, personal access tokens, project provisioning, native app authentication, local development, initialization, application creation, and project environment management.

Account authentication

Sign in with the same email and password used by the Gonvex dashboard:

npx gonvex login --runtime-url https://gonvex.example.com --email you@example.com

The password is prompted without echo. For non-interactive use, provide GONVEX_PASSWORD or --password. You can authenticate with an existing personal access token instead:

npx gonvex login --runtime-url https://gonvex.example.com --token gvx_pat_...

Use gonvex whoami to verify the active identity and permissions, and gonvex logout to remove the saved credential. Credentials are stored per runtime in $XDG_CONFIG_HOME/gonvex/config.json (or ~/.config/gonvex/config.json) with file mode 0600. GONVEX_CONFIG_PATH overrides that path, and GONVEX_ACCOUNT_TOKEN provides an environment-only credential.

Personal access tokens

An interactive account session can create account-level personal access tokens:

# Default CLI provisioning permissions:
# projects:read, projects:create, projects:keys:read
npx gonvex token create "Developer CLI"

# Broad project administration without account/token administration
npx gonvex token create "Project automation" --permission 'projects:*'

# Runtime-wide project administration (dashboard administrators only)
npx gonvex token create "Runtime automation" \
  --permission 'projects:*' --permission 'admin:projects'

# Explicit full account permissions
npx gonvex token create "Account automation" --full

Repeat --permission to grant multiple permissions. Run gonvex token permissions to list accepted values. The secret is returned only by the create response; the runtime stores a hash. List token metadata with gonvex token list and revoke a token with gonvex token revoke <token-id>. Project membership checks still apply unless an administrator explicitly grants admin:projects. Dashboard administrators can create and revoke the same runtime-wide credentials from their account profile on the project chooser.

gonvex project

List account projects or create and connect a new project entirely from the CLI:

npx gonvex project list
npx gonvex project create my-app
npx gonvex project select <project-id>

project create provisions the runtime project, receives its project ID and project key, and updates .env.local with GONVEX_PROJECT_ID, GONVEX_RUNTIME_URL, GONVEX_PROJECT_KEY, and the public Vite connection values. project select obtains the selected project's key and performs the same local setup. Both commands accept --runtime-url; use --project-root when configuring a directory other than the current one. Creating a project also accepts --database-mode single|multiTenant. Pass --json to project list or project create for the complete API response.

gonvex auth

Enable project-scoped Google login without Firebase or a per-app Google Cloud setup:

npx gonvex auth add google --origin http://localhost:5173
npx gonvex auth add google \
  --origin https://preview.example.com \
  --origin https://app.example.com \
  --signup-mode personal
npx gonvex auth remove google --origin https://preview.example.com

The default callback path is /; override it with --callback-path. The command requires the selected project's GONVEX_PROJECT_KEY, registers the exact callback with the runtime, updates gonvex.json, and writes gonvex/auth.tsx with GonvexAuthProvider, GoogleSignInButton, and useGonvexAuth exports. An untouched Vite React starter is wired automatically; custom applications keep their existing source and use the generated module explicitly.

Inspect the provider or list accounts created by successful sign-ins:

npx gonvex auth status
npx gonvex auth status --json
npx gonvex auth doctor
npx gonvex auth users
npx gonvex auth users --json

auth doctor checks the central broker configuration, provider state, exact callbacks recorded in gonvex.json, and invite-only bootstrap requirements. It exits non-zero on any issue, making it suitable for production deployment gates.

For a multi-tenant project, manage workspaces, invitations, memberships, and app accounts without direct database changes:

npx gonvex auth tenants list
npx gonvex auth tenants create "Acme" --owner owner@acme.example
npx gonvex auth memberships list --tenant <tenant-id>
npx gonvex auth memberships add --tenant <tenant-id> --email user@example.com --role member
npx gonvex auth memberships remove --tenant <tenant-id> --user <user-id>
npx gonvex auth memberships remove --tenant <tenant-id> --email pending@example.com
npx gonvex auth user disable <user-id>
npx gonvex auth user enable <user-id>
npx gonvex auth user delete <user-id>

Remove a retired callback with gonvex auth remove google --origin <url>; this keeps the provider enabled. Disable all new Google sign-ins with gonvex auth remove google. Existing account and session records are retained; disabling the provider prevents new authorization flows and removes native-auth enforcement from that project unless the runtime has GONVEX_REQUIRE_AUTH=true. The Gonvex runtime operator must configure one central Google OAuth client as described in Self-hosting and Deployment.

Native Google login applies to both single and multiTenant database modes. For single, --signup-mode personal is open signup into the shared project scope and inviteOnly requires an invitation whose tenant ID is the project ID. For multiTenant, personal creates a personal workspace on first sign-in and inviteOnly prevents public workspace creation.

gonvex init

Add the Vite React starter files to the current directory without overwriting existing files:

npx gonvex init [--template vite-react] [--project <id>] [--runtime <url>]

Option	Default
--template	vite-react
--project	current directory name
--runtime	http://localhost:8080

See Initialize an Existing Project for the required manual merge steps.

gonvex create

Create a local app directory from the complete starter:

npx gonvex create my-app [--template vite-react]

Most users should invoke the dedicated initializer package instead:

npm create gonvex@latest my-app

Both paths use vite-react by default. Creation fails if the target path already exists.

Provision the runtime project and ship a wired Google sign-in screen in the same command:

npm create gonvex@latest my-app -- \
  --runtime-url https://gonvex.example.com \
  --database-mode multiTenant \
  --google-auth \
  --origin https://my-app.example.com \
  --signup-mode inviteOnly \
  --owner owner@example.com

--google-auth implies --provision. Repeat --origin for preview and production sites. --owner is required for an invite-only app and bootstraps its first workspace/scope invitation in the same command. An HTTPS origin triggers auth doctor; use --allow-unready only while the runtime operator is deliberately completing the one-time Google broker setup. If provisioning fails, the CLI removes the newly created local directory and attempts to delete the new runtime project.

gonvex dev

Build the backend manifest, regenerate TypeScript bindings, sync the runtime, and watch gonvex/**/*.go:

npx gonvex dev

Run a frontend command alongside the watcher by placing it after --:

npx gonvex dev -- vite

Options

--project <path>       Project root; defaults to the current directory
--runtime-url <url>    Override the configured runtime URL
--project-id <id>      Override the configured project ID
--key <key>            Override the project key
--once                 Build and sync once, then exit
--verbose-logs         Print all streamed runtime calls, not only warnings/errors

--once cannot be combined with a child command. It exits non-zero when runtime sync does not succeed, making it suitable for CI checks.

The CLI loads settings in this order: command-line overrides, .env.local, .env, gonvex.json, the current runtime saved by gonvex login, then built-in defaults. A project ID encoded in a valid project key can also determine the selected project.

gonvex env

Manage server-side environment variables stored for the selected runtime project:

npx gonvex env list
npx gonvex env get NAME
npx gonvex env set NAME value
npx gonvex env push .env.production
npx gonvex env remove NAME

The command accepts the same --project, --runtime-url, --project-id, and --key connection options as dev. A GONVEX_PROJECT_KEY or equivalent --key is required. The CLI sends that key as both Authorization: Bearer … and x-gonvex-key; the runtime accepts it only when it is the key registered to the exact project ID in the request path. A different project's key, an arbitrary key, and an opaque runtime-wide GONVEX_DEV_SYNC_KEY cannot read or change project environment variables. A legacy single-project runtime may use its generated project key through that setting, but the key's encoded project ID must still match the request. Dashboard project owners and admins can manage the same variables with their signed-in session.

env push FILE (also available as env upload FILE) reads the file relative to the selected project root and atomically replaces the complete server-side variable set for that project. You can use --file FILE instead of the positional path. Keep the project connection settings in .env.local and upload a separate deployment env file; the CLI refuses files containing GONVEX_PROJECT_KEY, GONVEX_DEPLOY_KEY, or GONVEX_KEY so a project credential cannot be copied into function environments.

Runtime compatibility

Project-key authentication for /dev/projects/{project}/env requires runtime v0.1.9 or newer. Updating @gonvex/cli does not update a separately deployed runtime. If gonvex env list returns 401 with dashboard sign-in is required while gonvex dev --once succeeds with the same project settings, the runtime is using the v0.1.8-or-earlier environment handler. Rebuild and replace the runtime from the current Gonvex source as described in Self-hosting and Deployment.

A reverse proxy must preserve the Authorization and x-gonvex-key request headers and route /dev/projects/{project}/env to the runtime without rewriting the path.

Commands not implemented yet

The current npm CLI does not implement these commands:

gonvex tenant ...
gonvex deploy
gonvex generate
gonvex doctor

They are product roadmap concepts, not commands to use in current setup or deployment scripts. Development manifests are uploaded by gonvex dev.