📚 Help › CLI Access with SSO

CLI Access with SSO

SAML and OIDC are browser-only authentication flows. They authenticate you in a browser session, but command-line tools like hg cannot complete a browser redirect during a push or pull operation.

For CLI work — cloning, pushing, pulling, and LFS uploads/downloads — authenticate with a personal API token instead of your SSO credentials.

Generating a token

  1. Go to Settings → Tokens from your user menu (top-right).
  2. Click New token.
  3. Pick scopes:
    • repo:read for read-only operations (clone, pull).
    • repo:write for push and LFS uploads.
  4. Click Create. The token is shown once — copy it immediately. It is not recoverable after you leave the page.

Configuring ~/.hgrc

Add an [auth] section for your Isurus host:

[auth]
isurus.prefix = isurus.example.com
isurus.username = your.email@example.com
isurus.password = <paste token here>

The password field expects the token, not your SSO password. The username field can be anything — it is logged for auditing but not verified against SSO.

For multiple forges or multiple accounts, use a different prefix per entry:

[auth]
isurus_work.prefix = isurus.example.com
isurus_work.username = work@example.com
isurus_work.password = <work token>

isurus_personal.prefix = forge.home.example
isurus_personal.username = me@example.com
isurus_personal.password = <personal token>

Verifying

Clone or pull a private repo over HTTPS:

hg clone https://isurus.example.com/myorg/myrepo
cd myrepo
hg pull
hg push

All four should succeed without opening a browser.

Token scopes

Tokens can be scoped to one of three levels:

Scope level Range Recommended for
User Every repo the user can access Personal dev laptop
Org One organization Cross-project automation
Repo One repository CI agents, single-purpose scripts

Use the narrowest scope that gets the job done. Repo-scoped tokens are ideal for CI agents because a leaked token cannot be used against any other repo.

Revoking a token

In Settings → Tokens, click Revoke next to the token. Revocation is immediate — subsequent requests using that token return 401 Unauthorized.

SSH alternative

If you prefer, you can use SSH instead of HTTPS + tokens. Add your SSH public key in Settings → SSH Keys, then clone with:

hg clone ssh://hg@isurus.example.com/myorg/myrepo

SSH bypasses the API token system entirely. It does not require SSO and does not support LFS uploads over the SSH protocol — use HTTPS + tokens for LFS workflows.

×