Older builds lack the decision and credits groups. If sikaru decision --help still fails after installing, the newer CLI may be on a different PATH entry. Check which -a sikaru. If the installer doesn't work, tell the user and point them to https://github.com/aadi-labs/sikaru-clients. Don't build or download binaries from anywhere else.

2. Sign up or sign in

One flow covers both. A new user gets an organization named after them (for example "Ada's Team") and a default project. An existing user lands in their organization. The user approves in their own browser: never type their email, password or payment details into a form for them.

With the CLI (preferred)

sikaru login --no-browser

The command prints a one-time code and a verification URL on stderr. It then waits until the user approves or the code expires.

In an agent shell, run it in the background so your tool call doesn't time out. Read the code and URL from its output, give both to the user, and wait for the command to exit 0. If the code expires, run it again.
On success the CLI saves the default project and prints Using project .... No project ID needs to be copied from the dashboard.
At an interactive terminal, plain sikaru login opens the browser for the user. Any command run there while signed out starts sign-in automatically. Without a terminal, a signed-out command fails with an auth error, so sign in first.
If SIKARU_API_KEY is set, it overrides the sign-in. Unset it for personal access.
sikaru login --with-token reads a token the user pastes from standard input. Don't put the token on the command line, where it lands in shell history.

Without the CLI (agent registration)

Follow https://sikaru.ai/auth.md with the user's email. It registers you, has the user approve, and gives you a short-lived access token for Authorization: Bearer.

The approval link expires after about 5 minutes. Give it to the user immediately, and mint a new attempt if they're too late.
The user reads a code like ABCD-EFGH off the page. If completing the claim says the code is invalid, retry once without the hyphen (ABCDEFGH).
A new user's first call, whichever it is, creates their organization and default project. GET https://api.sikaru.ai/v1/projects returns defaultProjectId.
Model and System One calls without a Sikaru-Project header use the default project. Send the header to use another one.

3. Choose a different project (optional)

Sign-in already chose the default project. To switch:

sikaru config set project PROJECT_ID
sikaru config show

Commands with -p/--project use the saved project, or SIKARU_PROJECT if that is set. Signed-in inference and decision calls bill the saved project, else the organization's default project.

4. Check access

sikaru doctor

It checks the credential, the project and the workspace without starting a run.

Status	Meaning
401	The credential is missing, invalid, or pointed at the wrong endpoint. Sign in again.
403	The credential can't do that operation in this project. Use a key with that permission.
404	Wrong project or resource ID, or it isn't visible to this caller.

Don't fix an access failure by changing IDs or retrying.

5. Get an API key for code, servers and CI

SDKs and automation use a project API key, not the CLI sign-in. Install the published SDK for the project's language:

pip install sikaru-sdk               # or: uv add sikaru-sdk; import sikaru_sdk
npm install @aadi-labs/sikaru-sdk    # TypeScript, server-side code only

The user creates the key in the dashboard (https://app.sikaru.ai) for the project. Store it in the environment or a secret manager:

export SIKARU_API_KEY=...   # user pastes it; never echo it back
export SIKARU_PROJECT=PROJECT_ID

Grant only the permissions the integration needs:

Task	Permission
List agents and read runs and trajectories	`runs:read`
Create an agent	`managed_agents:write`
Start a run	`runs:create`
Read run events	`events:read`
Send tool results or approvals	`tool_results:write`
Manage connections	`tool_providers:write`
Make release decisions	`harness:write`

Keep the key on the backend. A browser or mobile app calls your backend, and the backend calls Sikaru.

6. Add credits (only when asked or when a run pauses for funding)

sikaru agent run exits with code 5 when a run is paused for funding. Check the balance first:

sikaru credits balance -o json   # {"state", "availableUsd", "topUpMaxUsd"}

`state`	What to do
`no_card`	No credits yet. Top up from an agent wallet (the first paid top-up opens the organization's credit account), or ask the user to save a card in Billing at https://app.sikaru.ai, which adds a one-time $5 starting credit. Don't enter card details for them.
`complimentary`	Usage is covered. No credits needed.
`ready` with `topUpMaxUsd` null	An organization admin turned agent top-ups off. Ask the user to add credits in Billing.
`ready`	Top up from an agent wallet, up to `topUpMaxUsd`.

To add credits from an agent wallet:

sikaru credits add --amount 20 -o json     # creates an offer; prints payUrl and id
sikaru credits status TOP_UP_ID            # "credited" once the payment lands

The minimum is 5 US dollars. Confirm the amount with the user before you create an offer. Give them the pay URL, or pay it only with a wallet they explicitly approved for this payment. Don't say credits were added until credits status reports credited. Then resume the paused run with the next command from its result.

Docs: https://sikaru.ai/auth.md, https://docs.sikaru.ai/get-started/authentication.md, https://docs.sikaru.ai/sdks-and-cli/cli-automation.md, https://docs.sikaru.ai/sdks-and-cli/credits.md

sikaru-setup

Set up Sikaru

1. Install the CLI