Skip to main content
If you’re running Kodus on your own infrastructure, the CLI works the same way — you just need to point it to your API.

​
Connect to Your Instance

1

Set the API URL

Tell the CLI where your Kodus API lives. Pick one method:
HTTPS is required. The CLI rejects non-HTTPS URLs for security. The only exception is localhost and 127.0.0.1 for local development.
Priority order: KODUS_API_URL env var > ~/.kodus/config.json apiUrl > default (https://api.kodus.io).
2

Authenticate

3

Verify the Connection

kodus auth status
You should see your authentication mode, organization name, and that the token is valid. If using verbose mode, the API URL being used is logged:
kodus auth status --verbose

​
Cloudflare Access (Zero Trust)

If your self-hosted API is behind Cloudflare Access, the CLI supports service token authentication. 
export KODUS_API_URL=https://kodus-api.yourcompany.com
export CF_ACCESS_CLIENT_ID=your-client-id.access
export CF_ACCESS_CLIENT_SECRET=your-client-secret
The CLI sends CF-Access-Client-Id and CF-Access-Client-Secret headers on every API request when configured. Priority: env vars > config file.

​
Config File Reference

The CLI stores configuration in ~/.kodus/config.json: 
{
  "apiUrl": "https://kodus-api.yourcompany.com",
  "teamKey": "kodus_xxxxx",
  "teamName": "Engineering",
  "organizationName": "Acme Corp",
  "cfAccessClientId": "your-client-id.access",
  "cfAccessClientSecret": "your-client-secret"
}
FieldRequiredDescription
apiUrlNoYour self-hosted API URL. Overridden by KODUS_API_URL env var.
teamKeyNoTeam API key (starts with kodus_). Overridden by KODUS_TEAM_KEY env var.
teamNameNoDisplay name for the team.
organizationNameNoDisplay name for the organization.
cfAccessClientIdNoCloudflare Access client ID. Overridden by CF_ACCESS_CLIENT_ID env var.
cfAccessClientSecretNoCloudflare Access client secret. Overridden by CF_ACCESS_CLIENT_SECRET env var.
The config file is created with 0600 permissions (owner read/write only). The directory ~/.kodus/ is created with 0700 permissions.

​
Environment Variables Summary

VariableDescription
KODUS_API_URLSelf-hosted API endpoint (HTTPS required, except localhost)
KODUS_TEAM_KEYTeam key for shared access
KODUS_TOKENCI/CD token for pipelines
CF_ACCESS_CLIENT_IDCloudflare Access client ID
CF_ACCESS_CLIENT_SECRETCloudflare Access client secret
KODUS_VERBOSESet to true to see the resolved API URL and request details

​
CI/CD Integration

For self-hosted instances in CI/CD pipelines, set the API URL and authentication as environment variables: 
- name: Kodus Review
  env:
    KODUS_API_URL: ${{ secrets.KODUS_API_URL }}
    KODUS_TEAM_KEY: ${{ secrets.KODUS_TEAM_KEY }}
  run: npx @kodus/cli review --format json --fail-on error
Use --fail-on error or --fail-on critical to fail the pipeline when issues above a severity threshold are found.

​
Distributing to Your Team

To onboard your team in one command, combine the API URL with the skill installer: 
KODUS_API_URL=https://kodus-api.yourcompany.com \
  curl -fsSL https://review-skill.com/install | bash -s -- --team-key kodus_xxxxx
This installs the CLI, configures the team key, and deploys review skills to detected AI agents (Claude Code, Cursor, Windsurf) — all pointing to your self-hosted instance.

​
Troubleshooting

The CLI requires HTTPS for all non-localhost URLs. Make sure your self-hosted instance has a valid TLS certificate. If you’re testing locally, use http://localhost:<port> instead.
  • Verify the URL is reachable: curl -I https://kodus-api.yourcompany.com
  • Check if a firewall or VPN is blocking the connection
  • If behind Cloudflare Access, ensure CF_ACCESS_CLIENT_ID and CF_ACCESS_CLIENT_SECRET are set
  • Use --verbose to see the exact URL being used
  • Run kodus auth status to check your current auth state
  • If using a team key, verify it’s valid on your self-hosted dashboard
  • If using personal login, tokens expire after 1 hour — the CLI auto-refreshes, but you may need to re-login if the refresh token is also expired
  • Make sure KODUS_API_URL points to the correct instance
This usually means the URL is hitting a reverse proxy, load balancer, or Cloudflare Access page instead of the actual API. Check:
  • The URL path is correct (no trailing /api or similar)
  • Cloudflare Access credentials are configured if applicable
  • The reverse proxy is forwarding requests correctly
Your self-hosted instance may enforce device limits per organization. Contact your admin to increase the limit or remove old devices from the dashboard.