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:

1. Generate a token in Plexicus Settings → API Tokens
2. Store it in an environment variable (PLEXICUS_API_TOKEN)
3. Tools read the token and authenticate on every request

Rolling out with the MCP release

The Settings → API Tokens page ships together with the MCP server release. If your workspace does not show it yet, it is being rolled out — contact support to enable it, or use your existing automation token in the meantime.

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 exchange tokens (interactive login)

Use case: Interactive CLI sessions where you want to log in once and stay authenticated.

How it works:

1. Run plexicus login in your terminal
2. CLI opens your browser to the Plexicus login page
3. You log in (2FA if enabled)
4. Browser redirects back to your CLI with a temporary token
5. CLI exchanges the temporary token for a bearer token and stores it locally

Scope: Full access to your organization's data (subject to your role).

Lifetime: Until you run plexicus logout or the token expires.

Best for: Interactive command-line workflows, local testing.

Personal API tokens

Generation

1. Log in to Plexicus
2. Go to Settings → API Tokens
3. Click + Generate Token
4. Enter a name (e.g., "GitHub Actions", "Local Dev", "MCP Server")
5. Choose expiry:
   • 30 days — recommended for CI/CD
   • 90 days — recommended for development
   • Never expires — less secure, use only for trusted integrations
6. Click Generate
7. 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:

1. Find the token in the list
2. Click Revoke
3. 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 .env files (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:

1. Opens your browser to the Plexicus login page
2. Displays a temporary code and callback URL
3. You log in and confirm (2FA if enabled)
4. Browser redirects with an authorization code
5. CLI exchanges the code for a bearer token and stores it locally

Storage location:

• Linux/Mac: ~/.plexicus/credentials
• Windows: %USERPROFILE%\.plexicus\credentials

The token is stored securely and reused for subsequent CLI commands.

Session status

Check your current session:

plexicus auth status

This shows the authenticated user and organization.

Logout

End your session:

plexicus logout

This deletes the stored token. Subsequent commands will require re-authentication.

Token lifecycle

CLI exchange tokens expire based on your session:

• Typically valid for 24 hours of inactivity
• Refresh automatically on each use
• Revoked when you run plexicus logout
• Deleted when you clear your credentials

Token comparison

Aspect	Personal API Token	CLI Exchange Token
Flow	Direct environment variable	Browser login → CLI exchange
Setup time	1 minute (generate in settings)	~30 seconds (run plexicus login)
Storage	Environment variable (your responsibility)	Secure local file (~/.plexicus/credentials)
Scope	Full access	Full access
Expiry	Configurable (30/90 days or never)	Session-based (~24h inactivity)
Revocation	Manual in Settings	Automatic on logout
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_TOKEN to verify the token is set
• Fix: Generate a new token in Settings → API Tokens

CLI Exchange Token:

• Session expired (typically 24h inactivity)
• Fix: Run plexicus login again

"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:

1. Generate a personal API token in Settings → API Tokens instead
2. Export it: export PLEXICUS_API_TOKEN=<token>
3. Use the CLI without the login flow

Token rotation

To rotate your token (replace an old one before expiry):

1. Generate a new token in Settings → API Tokens
2. Update your environment variable or CI/CD secret
3. Test with the new token
4. Revoke the old token in Settings → API Tokens

This approach ensures no downtime during rotation.

Security recommendations

1. Use environment variables: Never hardcode tokens in scripts or config files (except in CI/CD secrets).
2. Add .env to .gitignore: If storing tokens locally for development, exclude them from git.
3. Rotate regularly: Set a 30–90 day expiry for personal tokens.
4. Monitor usage: Check "Last used" in Settings to identify unused tokens.
5. Revoke on compromise: If a token is exposed, revoke it immediately in Settings.
6. Use separate tokens: Consider one token per tool (e.g., CI, local IDE, scripts) for easier revocation.