Access & the raw API

These commands are how the CLI knows which Alaf Server it's talking to and who you are — plus an escape hatch (alaf server api) for reaching any route that doesn't have its own command yet.

alaf server login

Authenticate against an instance and save the token into a context. Run with no --token and it opens the dashboard's Settings page — where Personal Access Tokens live — and waits for you to paste one; pass --token to log in non-interactively (CI, scripts). The token is validated against the API before it's stored, and it must start with opsh_pat_.

# Interactive — opens the dashboard, prompts for a pasted token
alaf server login

# Non-interactive — against a remote self-hosted instance, stored as a named context
alaf server login \
  --token opsh_pat_xxxxxxxx \
  --api-url https://alaf server.example.com \
  --dashboard-url https://alaf server.example.com \
  --context prod

alaf server logout

Remove the stored token from a context. The endpoints stay saved, so a later login just re-adds the token.

alaf server logout                 # active context
alaf server logout --context prod  # a specific one

alaf server context

Manage the named connections in ~/.alaf server/config.json. This is pure local config editing — no API calls. Use it to keep several instances side by side (local, staging, production) and switch between them. Alias: alaf server ctx. Running it bare prints the active context and the full list (the active row is starred).

alaf server context           # show active + list all
alaf server context use prod  # switch the active context

The list shows one row per context: current (* marks the active one), name, apiUrl, dashboardUrl, and auth (token when a token is stored, - when not).

context add

Register an instance without logging in interactively. add only writes config — use login when you want the token checked against the API first.

alaf server context add staging \
  --api-url https://staging.example.com \
  --dashboard-url https://staging.example.com \
  --token opsh_pat_xxxxxxxx \
  --use

alaf server token

Create and manage the personal access tokens that authenticate the CLI and the API. Tokens are self-scoped — every call operates on your own tokens. In the dashboard these live under Settings → Personal Access Tokens.

token create

# A full-access, non-expiring token
alaf server token create "laptop"

# A read-only token that expires in 30 days
alaf server token create "ci-reader" --read-only --expires 30

# Scope a token to one project with specific permissions (repeatable)
alaf server token create "deploy-bot" --grant project:abc123:read,write

The list table shows: id, name, prefix, readOnly, scoped, expires, lastUsed, and revoked. Pass a token's id (they look like pat_…) to revoke:

alaf server token list
alaf server token revoke pat_abc123

alaf server api

The escape hatch. Make an authenticated request to any API route using the active context's token — much like gh api. This is what keeps the CLI small: anything without a dedicated command (audit log, one-off reads, routes added after your CLI version) is still reachable here.

The <path> argument is relative to /api, so alaf server api /projects calls <your-api-url>/api/projects. The method defaults to GET, or POST when you pass --data.

# GET a collection
alaf server api /projects

# GET a single resource
alaf server api /deployments/dep_abc123

# POST with a JSON body (method defaults to POST when --data is given)
alaf server api /domains -d '{"projectId":"proj_123","hostname":"app.example.com"}'

# DELETE with an explicit method
alaf server api /tokens/pat_abc123 -X DELETE

# Add query parameters (repeatable)
alaf server api /domains -q projectId=proj_123

The response body is printed to stdout — pretty-printed when it's JSON, raw otherwise. On a non-2xx response the body is still printed and the command exits non-zero, so you can pipe it into jq and still detect failures in scripts.