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 (override with ISLO_OAUTH_PORT).
2. Opens your default browser to the Descope authorization URL.
3. You authenticate via Google, email, or SSO.
4. Descope redirects to localhost with an authorization code.
5. The CLI exchanges the code for access and refresh tokens.
6. Tokens are stored securely on your system (see Token Storage).

Troubleshooting:

If the browser doesn’t open automatically:

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

islo logout

Clear stored authentication tokens.

Syntax:

$
islo logout

islo switch

Switch between organizations you belong to.

Syntax:

$
islo switch

Behavior:

1. Prints your current organization.
2. Opens a browser for an OAuth flow that lets you pick a different org.
3. Replaces your stored credentials with the new org’s tokens.

After the flow, run islo status to confirm the new org.

Integrations Login

Connect external services so sandbox sessions and Islo features can use them without you managing credentials in islo.yaml or env vars.

Syntax:

$
islo login --tool <service>

Supported integrations:

• github — GitHub repo and code access (personal + team)
• slack — Slack workspace notifications (team)
• linear — Linear project management and issues (team)
• notion — Notion workspace for notes and docs (team)
• atlassian — Atlassian (Jira, Confluence) (team)
• anthropic (alias: claude) — Anthropic API key for Claude models (personal)
• cursor — Cursor API key for Cursor CLI in sandboxes (personal)
• openai — OpenAI API key for GPT models (personal)

“Personal” connections apply only to your user. “Team” connections apply to everyone in the org.

Examples:

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

Integration tokens are stored securely and used automatically when needed.

islo status

Show your authentication state, connected integrations, project configuration, and sandboxes.

Syntax:

$
islo status

Output:

Sections for authentication state, connected integrations, project configuration from islo.yaml, environment/secret guidance, and your sandboxes.

Example output:

Authentication
  Status: Logged in
  Org: Acme Corp
  Tier: team
  Expires: <Date-Time>
Connected Integrations
  github ✓ (user)
  github ✓ (team)
  linear ✓ (team)
  anthropic ✓ (user)
  Integrations power Islo features, but sandbox CLIs such as 'gh' may still need their own token or login inside the sandbox.
Project Configuration
  Memory: 4096 MB
Environment & Secrets
  Persistent sandbox env comes from 'islo.yaml' env plus any '--env KEY=VALUE' flags.
  Agent-specific credentials should come from integrations or explicit '--env KEY=VALUE' flags when needed.
Your Sandboxes
  my-project       running
  backend-dev      running
  api-tests        stopped
  Tip: Run 'islo ls --all' to see team sandboxes

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

The CLI refreshes expired access tokens automatically. When the refresh token itself expires or becomes invalid, the next command prints a message asking you to login again. Re-authenticate with:

$
islo login

See Troubleshooting → Authentication for the full message variants.

API Key Authentication

For CI/CD pipelines, scripts, and other non-interactive callers, use an API key instead of OAuth. Set ISLO_API_KEY in the environment and the CLI skips the browser flow:

$
export ISLO_API_KEY=islo_key_…
$
islo ls

API Key vs OAuth

See API Keys for creating, listing, rotating, and using keys.