convexq-cli

name	convexq-cli
description	Manage Convex Platform API via CLI - auth, teams, projects, deployments, tokens, raw. Use when user mentions 'Convex', 'team token', 'list Convex projects', 'create deployment', 'preview deploy key', 'custom domain', 'environment variables', or wants to orchestrate Convex teams, projects, and deployments from the terminal.
category	devtools

convexq-cli

When To Use This Skill

Use the convexq-cli skill when you need to:

• inspect Convex team, project, deployment, token, or domain state from the terminal
• create or delete Convex projects, deployments, deploy keys, preview keys, or team tokens
• manage project defaults like environment variables or deployment settings
• automate Convex admin workflows with stable --json output
• hit a documented Convex Management API endpoint that does not yet have a high-level command via raw

Capabilities

• Read operations: inspect token details, list team projects, list team or project deployments, fetch project records, inspect deploy keys, preview keys, custom domains, team members, deployment classes, deployment regions, and default env vars.
• Write operations: create teams, invite members, create team access tokens, create or delete projects, create or update deployments, transfer deployments, create or delete deploy keys, create or delete preview keys, create or delete custom domains, and update project default env vars.
• Token management: store the active Convex token locally, verify it against /token_details, and manage personal access tokens.
• Automation-safe output: every command supports --json and returns the standard api2cli envelope.
• Escape hatch: raw get, raw post, and raw patch let agents call any current or newly added Management API path without waiting for a wrapper update.

Common Use Cases

• "List every Convex project in this team and show me the project IDs."
• "Create a preview deploy key for this project."
• "Fetch the default prod deployment for this project."
• "Update a deployment reference or class."
• "List default environment variables for a project, then update one."
• "Call a Management API endpoint directly and give me the JSON."

Setup

If convexq-cli is missing, rebuild and relink it:

bun --version || curl -fsSL https://bun.sh/install | bash
npx api2cli bundle convexq
npx api2cli link convexq

Always use --json for agent-driven calls.

Authentication

convexq-cli auth set "your-token"
convexq-cli auth test --json

Auth commands: auth set <token>, auth show, auth remove, auth test

Token path: ~/.config/tokens/convexq-cli.txt

Resources

auth

Command	Description
convexq-cli auth set <token>	Save the active Convex team-scoped or OAuth token locally.
convexq-cli auth show	Show the stored token in masked form.
convexq-cli auth remove	Delete the stored token.
convexq-cli auth test --json	Validate the token against the Convex Management API.

teams

Command	Description
convexq-cli teams create --name "My Team" --default-region aws-us-east-1 --json	Create a Convex team.
convexq-cli teams members <teamId> --json	List team members.
convexq-cli teams invite <teamId> --email "[e-mail]" --role developer --json	Invite a member to a team.
convexq-cli teams access-token <teamId> --json	Create a new team access token.
convexq-cli teams projects <teamId> --json	List all projects in a team.
convexq-cli teams deployments <teamId> --deployment-type prod --json	List team deployments with filters.
convexq-cli teams local-deployments <teamId> --json	List local deployments for a team.
convexq-cli teams deployment-classes <teamId> --json	List available deployment classes.
convexq-cli teams deployment-regions <teamId> --json	List available deployment regions.

projects

Command	Description
convexq-cli projects create <teamId> --name "My App" --deployment-type prod --json	Create a project, optionally with an initial deployment.
convexq-cli projects get <projectId> --json	Fetch a project by ID.
convexq-cli projects resolve <teamIdOrSlug> <projectSlug> --json	Fetch a project by team slug or ID plus project slug.
convexq-cli projects delete <projectId> --json	Delete a project.
convexq-cli projects deployments <projectId> --deployment-type preview --json	List deployments for a project.
convexq-cli projects deployment <projectId> --default-prod true --json	Fetch a deployment from a project by ID.
convexq-cli projects deployment-resolve <teamIdOrSlug> <projectSlug> --reference staging --json	Fetch a deployment from team/project slug resolution.
convexq-cli projects create-deployment <projectId> --type preview --reference pr-123 --json	Create a deployment in a project.
convexq-cli projects preview-keys <projectId> --include-managed true --json	List preview deploy keys.
convexq-cli projects create-preview-key <projectId> --name "GitHub Preview" --json	Create a preview deploy key.
convexq-cli projects delete-preview-key <projectId> --id "token-or-name" --json	Delete a preview deploy key.
convexq-cli projects envs <projectId> --deployment-type prod --json	List default environment variables.
convexq-cli projects update-envs <projectId> --change '{"name":"FOO","value":"bar","deploymentTypes":["prod"],"operation":"upsert"}' --json	Update project default environment variables.

deployments

Command	Description
convexq-cli deployments get <deploymentName> --json	Fetch a deployment by deployment name.
convexq-cli deployments update <deploymentName> --reference staging --json	Update deployment settings like class, type, reference, defaults, or logs.
convexq-cli deployments delete <deploymentName> --json	Delete a deployment.
convexq-cli deployments transfer <deploymentName> --destination-project-id <projectId> --json	Transfer a deployment to another project.
convexq-cli deployments deploy-keys <deploymentName> --json	List deploy keys for a deployment.
convexq-cli deployments create-deploy-key <deploymentName> --name "CI Key" --json	Create a deploy key.
convexq-cli deployments delete-deploy-key <deploymentName> --id "token-or-name" --json	Delete a deploy key.
convexq-cli deployments domains <deploymentName> --json	List custom domains for a deployment.
convexq-cli deployments create-domain <deploymentName> --domain api.example.com --request-destination convexCloud --json	Create a custom domain.
convexq-cli deployments delete-domain <deploymentName> --domain api.example.com --request-destination convexCloud --json	Delete a custom domain.

tokens

Command	Description
convexq-cli tokens details --json	Get details for the currently stored token.
convexq-cli tokens list --limit 20 --json	List personal access tokens.
convexq-cli tokens create --name "automation" --json	Create a personal access token.
convexq-cli tokens delete --id "token-or-name" --json	Delete a personal access token.

raw

Command	Description
convexq-cli raw get --path /token_details --json	GET any Management API path directly.
convexq-cli raw get --path /teams/297110/list_deployments --param limit=10 --json	GET a path with query params.
convexq-cli raw post --path /create_personal_access_token --body '{"name":"automation"}' --json	POST any Management API path with a JSON body.
convexq-cli raw patch --path /deployments/my-deployment --body '{"reference":"staging"}' --json	PATCH any Management API path with a JSON body.

Output Format

--json returns a standardized envelope:

{ "ok": true, "data": { ... }, "meta": { "total": 42 } }

On error:

{ "ok": false, "error": { "code": 401, "message": "401: Unauthorized", "suggestion": "Check your token: convexq-cli auth test" } }

Quick Reference

convexq-cli --help
convexq-cli <resource> --help
convexq-cli <resource> <action> --help

Global Flags

All commands support: --json, --format <text|json|csv|yaml>, --verbose, --no-color, --no-header

Exit codes: 0 success, 1 API error, 2 usage error