Skip to main content

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:

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

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:

  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. 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)
  5. 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​

  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 authorization page
  2. You log in if needed (2FA if enabled)
  3. Plexicus creates a personal API token named CLI - <date> for your user (token creation is limited to 5 per minute per IP address)
  4. 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​

AspectPersonal API TokenCLI Exchange Token
FlowDirect environment variableBrowser login → CLI exchange
Setup time1 minute (generate in settings)Run plexicus login
StorageEnvironment variable (your responsibility)Local file in ~/.config/plexicus
ScopeFull accessFull access
ExpiryConfigurable (30/90 days or never)365 days
RevocationManual in SettingsManual in Settings (plexicus logout only removes the local copy)
Best forAutomation, CI/CD, MCPInteractive CLI, local development
SecurityRequires .gitignore disciplineAutomatically 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:

  • The token expired or was revoked in Settings → API Tokens
  • 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.