Skip to main content
Manage authentication with Convex on your local machine. The login command authenticates your device, while logout removes your credentials.

​
convex login

Login to Convex to authenticate your device for using the CLI.

​
Usage

npx convex login [options]

​
Options

​
--device-name
string
Provide a name for the device being authorized. This helps identify different machines in your account settings.
npx convex login --device-name "Work Laptop"
​
--force
boolean
Proceed with login even if a valid access token already exists for this device. Use this to switch accounts or refresh authentication.
npx convex login --force
​
--no-open
boolean
Don’t automatically open the login link in the default browser. The URL will be printed to the console instead.
npx convex login --no-open
​
--login-flow
string
How to log in. Options: paste, auto, poll. Defaults to auto (guesses based on the environment).
  • auto: Automatically choose the best method
  • paste: Manual token paste flow
  • poll: Poll for authentication completion
npx convex login --login-flow paste

​
Examples

​
First-time login

Authenticate your device for the first time: 
npx convex login
This will:
  1. Open your browser to the Convex authentication page
  2. Ask you to authorize the device
  3. Save the authentication token locally

​
Login on a remote server

When SSH’d into a server where you can’t open a browser: 
npx convex login --no-open
Copy the URL printed to the console and open it in a browser on your local machine.

​
Name your device

Identify different machines in your account: 
npx convex login --device-name "CI Server"

​
Switch accounts

Log in with a different account: 
npx convex login --force

​
Login in CI/CD

Use the manual paste flow for automation: 
npx convex login --login-flow paste --no-open

​
convex login status

Check your login status and list accessible teams.

​
Usage

npx convex login status

​
Examples

​
Check login status

See if you’re logged in and which teams you have access to: 
npx convex login status
Example output: 
Convex account token found in: /Users/you/.convex/config.json
Status: Logged in
Teams: 2 teams accessible
  - My Personal Team (my-team)
  - Company Team (company)

​
convex logout

Log out of Convex on this machine by removing your stored credentials.

​
Usage

npx convex logout

​
Examples

​
Log out

Remove authentication from your device: 
npx convex logout
Output: 
You have been logged out of Convex.
  Run `npx convex dev` to log in.

​
Switch to a different account

Log out and then log back in with different credentials: 
npx convex logout
npx convex login

​
Authentication details

​
Where credentials are stored

Authentication tokens are stored in your global Convex configuration file:
  • macOS/Linux: ~/.convex/config.json
  • Windows: %USERPROFILE%\.convex\config.json

​
Device authorization

Each device you use the CLI on needs to be authorized. You can:
  • View all authorized devices in your Convex dashboard account settings
  • Revoke device access at any time
  • Name devices for easy identification

​
Team access

After logging in, you can:
  • Access all teams you’re a member of
  • Create new projects in any team
  • Deploy to any deployment you have permissions for
Use npx convex login status to see which teams you have access to.

​
Common workflows

​
First-time setup

# Login
npx convex login

# Verify login worked
npx convex login status

# Start development
npx convex dev

​
CI/CD setup

For CI/CD pipelines, use deploy keys instead of user login: 
# Set deploy key as environment variable
export CONVEX_DEPLOY_KEY="your-deploy-key"

# Deploy without login
npx convex deploy --prod
Deploy keys can be created in your project settings in the Convex dashboard.

​
Switching accounts

# Log out of current account
npx convex logout

# Log in with new account
npx convex login

# Verify new account
npx convex login status

​
Remote development

When developing on a remote server: 
# Get login URL without opening browser
npx convex login --no-open --device-name "AWS Dev Server"

# Copy the URL and open in your local browser
# Complete authentication
# Return to terminal and continue

​
Troubleshooting

​
Already logged in message

If you see “This device has previously been authorized”, you’re already logged in. To force a new login: 
npx convex login --force

​
Browser doesn’t open

If the browser doesn’t open automatically: 
npx convex login --no-open
Then manually copy and open the URL shown in your terminal.

​
Invalid or expired token

If you get authentication errors, log out and log back in: 
npx convex logout
npx convex login

Build docs developers (and LLMs) love

Get started for freeTalk to us