Authentication Commands

Islo supports two authentication methods:

1. OAuth 2.0 (default) - Browser-based login for interactive use
2. API Keys - For CI/CD, scripts, and programmatic access

islo login

Authenticate with Islo via browser-based OAuth flow.

Syntax:

$
islo login

Behavior:

1. Starts a local HTTP server on port 9876
2. Opens your default browser to the Descope authorization URL
3. User authenticates via Google, email, or SSO
4. Descope redirects to localhost with authorization code
5. CLI exchanges code for access and refresh tokens
6. Tokens are stored securely on your system

Expected output:

Opening browser for authentication...
Waiting for authentication...
Successfully logged in!

Exit codes:

Troubleshooting:

If the browser doesn’t open automatically:

1. Copy the URL printed in the terminal
2. Paste it in your browser manually
3. Complete the login flow
4. The CLI will catch the callback automatically

islo logout

Clear stored authentication tokens.

Syntax:

$
islo logout

Expected output:

Logged out successfully

Exit codes:

islo switch

Switch between tenants (organizations) if you belong to multiple.

Syntax:

$
islo switch

Behavior:

1. Lists all tenants/organizations you belong to
2. Prompts you to select one
3. Updates your active tenant

Your current tenant is shown in islo status output.

Example:

$
islo switch
$
# Select from:
$
# 1. Personal
$
# 2. Acme Corp
$
# 3. Open Source Project

Integrations Login

Connect external services like GitHub, Claude, or GitLab for enhanced functionality.

Syntax:

$
islo login --tool <service>

Supported integrations:

1. GitHub
2. Claude
3. Cursor
4. Linear

Examples:

$
# Connect GitHub for private repo access
$
islo login --tool github
$
$
# Connect Anthropic for Claude agent
$
islo login --tool claude

Integration tokens are stored securely and used automatically when needed.

islo status

Check your current authentication status along with configuration and tools.

Syntax:

$
islo status

Output:

Shows authentication state, current tenant, configuration from islo.yaml, connected integrations, and detected tools.

Example output:

Authentication: Logged in as user@example.com
Tenant: Acme Corp
Integrations:
  GitHub: Connected
  Claude: Connected
Configuration (islo.yaml):
  sandbox: my-project
  tools: python@3.12, node@20
Detected tools: python, node, postgres

Token Storage

Islo stores tokens securely using platform-specific backends:

Token Types

The CLI automatically refreshes expired access tokens using the refresh token. If the refresh token expires, you’ll need to run islo login again.

OAuth Port Configuration

The OAuth callback uses port 9876 by default. To use a different port:

$
export ISLO_OAUTH_PORT=9999
$
islo login

Session Expiration

When your session expires, commands will show:

Session expired. Please login again.

Fix: Run islo login to re-authenticate.

API Key Authentication

For CI/CD pipelines, scripts, and programmatic access, use API keys instead of OAuth.

Creating API Keys

Use islo api-key create to generate API keys:

$
# Create key (copied to clipboard by default)
$
islo api-key create my-ci-key
$
$
# Create key with expiration (90 days)
$
islo api-key create my-key --expires 90
$
$
# Save key to file
$
islo api-key create my-key --output-file key.txt
$
$
# Display key in terminal
$
islo api-key create my-key --show

Note: The key is only shown once at creation time. Store it securely.

Managing API Keys

$
# List all API keys
$
islo api-key list
$
$
# Deactivate a key (temporarily disable)
$
islo api-key deactivate <key-id>
$
$
# Reactivate a key
$
islo api-key activate <key-id>
$
$
# Delete a key permanently
$
islo api-key delete <key-id>

Using API Keys

Set the ISLO_API_KEY environment variable:

$
export ISLO_API_KEY=islo_key_abc123...
$
$
# Now all commands authenticate with the API key
$
islo use my-sandbox -- npm test
$
islo ls

Or pass it inline:

$
ISLO_API_KEY=islo_key_abc123 islo use ci-sandbox -- ./run-tests.sh

CI/CD Example

1
# GitHub Actions example
2
jobs:
3
  test:
4
    runs-on: ubuntu-latest
5
    steps:
6
      - uses: actions/checkout@v4
7
      - name: Run tests in Islo sandbox
8
        env:
9
          ISLO_API_KEY: ${{ secrets.ISLO_API_KEY }}
10
        run: |
11
          curl -fsSL https://islo.dev/install.sh | sh
12
          islo use ci-${{ github.run_id }} -- npm test
13
          islo rm ci-${{ github.run_id }} -f

API Key vs OAuth

API keys inherit permissions from the user who created them.