CLI & IDE Authentication
By the end of this page, you'll understand the two authentication flows available for CLI and IDE integration: personal API tokens for programmatic access and CLI exchange tokens for interactive login.
Authentication flows
Plexicus supports two ways to authenticate CLI and IDE tools:
1. Personal API tokens (recommended for CI/CD and scripts)
Use case: Automated workflows, scripts, integrations, and IDE plugins (MCP).
How it works:
- Generate a token in Plexicus Settings → API Tokens
- Store it in an environment variable (
PLEXICUS_API_TOKEN) - Tools read the token and authenticate on every request
Scope: Full access to your organization's data (subject to your role and plan).
Lifetime: Configurable expiry (30 days, 90 days, or never) or manual revocation.
Best for: CI/CD pipelines, scheduled scripts, MCP servers, local development.
2. CLI tokens (interactive login)
Use case: Interactive CLI sessions where you want to log in once and stay authenticated.
How it works:
- Run
plexicus loginin your terminal - CLI opens your browser to the Plexicus login page
- You log in (2FA if enabled)
- Plexicus creates a personal API token named
CLI - <date>and your browser hands it to the CLI on a local address (127.0.0.1) - The CLI stores the token locally
Scope: Full access to your organization's data (subject to your role).
Lifetime: The token is valid for 365 days. It is listed in Settings → API Tokens, where you can revoke it at any time, and plexicus logout removes the stored copy.
Best for: Interactive command-line workflows, local testing.
Personal API tokens
Generation
- Log in to Plexicus
- Go to Settings → API Tokens
- Click + Generate Token
- Enter a name (e.g., "GitHub Actions", "Local Dev", "MCP Server")
- Choose expiry:
- 30 days — recommended for CI/CD
- 90 days — recommended for development
- Never expires — less secure, use only for trusted integrations
- Click Generate
- Copy the token immediately (displayed only once)
Environment variable setup
Store your token in PLEXICUS_API_TOKEN:
Bash/Zsh:
export PLEXICUS_API_TOKEN="<your-token>"
Add to .bashrc / .zshrc for persistence:
echo 'export PLEXICUS_API_TOKEN="<your-token>"' >> ~/.bashrc
source ~/.bashrc
Windows PowerShell:
$env:PLEXICUS_API_TOKEN = "<your-token>"
Add to profile for persistence:
Add-Content -Path $PROFILE -Value '$env:PLEXICUS_API_TOKEN = "<your-token>"'
Listing tokens
View all active tokens in Settings → API Tokens. Each token shows:
- Name: User-assigned label
- Created: Generation date
- Expires: Expiry date (or "Never" if no expiry)
- Last used: When the token was last used (helps identify stale tokens)
Revocation
Revoke a token immediately in Settings → API Tokens:
- Find the token in the list
- Click Revoke
- Confirm (revocation is instant)
Revoked tokens stop working immediately. Any active requests using that token will fail with 401 Unauthorized.
Best practices
- Rotate regularly: Set a 30–90 day expiry and regenerate before it expires
- Limit scope: Consider using separate tokens for different tools (e.g., one for CI, one for local IDE)
- Never commit: Use environment variables or
.envfiles (add to.gitignore) - Monitor usage: Check "Last used" in Settings to identify unused tokens and revoke them
- Treat as secrets: If you suspect a token is compromised, revoke it immediately
CLI exchange tokens
Interactive login
Authenticate interactively in the CLI:
plexicus login
This command:
- Opens your browser to the Plexicus authorization page
- You log in if needed (2FA if enabled)
- Plexicus creates a personal API token named
CLI - <date>for your user (token creation is limited to 5 per minute per IP address) - Your browser hands the token to the CLI on a local address and the CLI stores it
Storage location: the Plexicus configuration directory (~/.config/plexicus).
The token is reused for subsequent CLI commands.
Logout
End your session:
plexicus logout
This deletes the stored token from your machine. The token itself remains valid until you revoke it in Settings → API Tokens.
Token lifecycle
CLI tokens are personal API tokens:
- Valid for 365 days from creation
- Visible and revocable in Settings → API Tokens
- Removed from your machine when you run
plexicus logout
Token comparison
| Aspect | Personal API Token | CLI Exchange Token |
|---|---|---|
| Flow | Direct environment variable | Browser login → CLI exchange |
| Setup time | 1 minute (generate in settings) | Run plexicus login |
| Storage | Environment variable (your responsibility) | Local file in ~/.config/plexicus |
| Scope | Full access | Full access |
| Expiry | Configurable (30/90 days or never) | 365 days |
| Revocation | Manual in Settings | Manual in Settings (plexicus logout only removes the local copy) |
| Best for | Automation, CI/CD, MCP | Interactive CLI, local development |
| Security | Requires .gitignore discipline | Automatically isolated, no commit risk |
IDE setup with tokens
MCP server (Claude Code, Cursor, VS Code, Windsurf)
Use a personal API token for the MCP server (see MCP Server Integration):
claude mcp add plexicus \
-e PLEXICUS_API_TOKEN=<your-token> \
-- uvx plexicus-mcp
VS Code / JetBrains IDE extensions
(Future IDE extensions will support both flows; consult the extension README for setup instructions.)
Troubleshooting
"Authentication failed" or "401 Unauthorized"
Personal API Token:
- Token is invalid, expired, or revoked
- Check:
echo $PLEXICUS_API_TOKENto verify the token is set - Fix: Generate a new token in Settings → API Tokens
CLI Exchange Token:
- The token expired or was revoked in Settings → API Tokens
- Fix: Run
plexicus loginagain
"Token not found" or "No credentials"
Cause: Environment variable is not set or credentials file doesn't exist.
Fix:
- For personal tokens:
export PLEXICUS_API_TOKEN=<your-token> - For CLI: Run
plexicus login
"Cannot open browser" during login
Cause: Headless environment (no display) or restricted network.
Workaround:
- Generate a personal API token in Settings → API Tokens instead
- Export it:
export PLEXICUS_API_TOKEN=<token> - Use the CLI without the login flow
Token rotation
To rotate your token (replace an old one before expiry):
- Generate a new token in Settings → API Tokens
- Update your environment variable or CI/CD secret
- Test with the new token
- Revoke the old token in Settings → API Tokens
This approach ensures no downtime during rotation.
Security recommendations
- Use environment variables: Never hardcode tokens in scripts or config files (except in CI/CD secrets).
- Add
.envto.gitignore: If storing tokens locally for development, exclude them from git. - Rotate regularly: Set a 30–90 day expiry for personal tokens.
- Monitor usage: Check "Last used" in Settings to identify unused tokens.
- Revoke on compromise: If a token is exposed, revoke it immediately in Settings.
- Use separate tokens: Consider one token per tool (e.g., CI, local IDE, scripts) for easier revocation.