CLI authentication

Sign in once from your browser, or hand the CLI an API key on a headless machine. Either way it stores what it needs and reuses it on every call 🔑

The simplest path opens your browser (OAuth 2.1 with PKCE):

idapt login

On a headless machine or over SSH, idapt login automatically falls back to a device code: it prints a short code and a URL you open in any browser to approve the session. Confirm you are signed in with:

idapt whoami

Sign out and clear the stored credential with idapt logout.

Use an API key in CI

Automations authenticate with an API key instead of a browser session. Create one under Settings → Developer(keys start with uk_), then give it to the CLI one of two ways:

Set the IDAPT_API_KEY environment variable. The CLI picks it up automatically and it takes precedence over a stored login.
Pipe it in without it touching the environment or your shell history: printf '%s' "$KEY" | idapt login --api-key-stdin.

Point the CLI at a different environment with IDAPT_API_URL. See API keys and scopes for scopes, version pinning, and spend caps.

Store the key as a CI secret and set IDAPT_API_KEY from it. Never commit a key or pass it as a plain command-line flag, where it can land in process listings and logs.

Where credentials live

The CLI writes your credential to <config>/idapt/cli-auth.json(mode 0600), under the standard config directory for your platform. The idapt-computer daemon has no user credential at all: it authenticates as the machine, so the two can never clash on a shared machine.

The @idapt/cli package has no config file and no config command. Everything it needs comes from your login, the environment variables above, and the ambient context below.

Switch between accounts

The CLI can hold several signed-in accounts side by side, so a personal and a work account no longer take turns. Sign in again to add one, then switch whenever you like:

idapt auth list
idapt auth switch work

The account you are using carries its own workspace and agent selection, so switching accounts switches those too. Use --context work for a single command, or set IDAPT_CONTEXT for a whole shell.

idapt auth rename and idapt auth remove tidy the list. Removing the one you are using falls back to another rather than leaving you signed out of everything.

Set the workspace and agent you act as

Most commands run against a workspace. Rather than pass it every time, pin an ambient context that later commands inherit:

idapt workspace use <workspace-id>   # pin the active workspace
idapt workspace current              # show it
idapt workspace clear                # unset it

idapt agent use <agent-id>           # act as an agent
idapt agent current
idapt agent clear

To override the workspace for a single command, pass --workspace-id <id>. idapt whoami always shows who and where you are acting.

API keys and scopes

Create a key, choose its scopes, pin it to an API version, rotate it, and cap what it can spend.

Command reference

The idapt <resource> <verb> grammar, how to discover any command from the terminal, and the full command list.

Installing the CLI

Install, sign in, upgrade, and uninstall the idapt CLI on macOS, Linux, and Windows.

Up next

Command reference

The idapt <resource> <verb> grammar, how to discover any command from the terminal, and the full command list.

Was this helpful?

Sign in once from your browser, or hand the CLI an API key on a headless machine. Either way it stores what it needs and reuses it on every call 🔑

The simplest path opens your browser (OAuth 2.1 with PKCE):

idapt login

idapt whoami

Sign out and clear the stored credential with idapt logout.

Use an API key in CI

Automations authenticate with an API key instead of a browser session. Create one under Settings → Developer(keys start with uk_), then give it to the CLI one of two ways:

Set the IDAPT_API_KEY environment variable. The CLI picks it up automatically and it takes precedence over a stored login.
Pipe it in without it touching the environment or your shell history: printf '%s' "$KEY" | idapt login --api-key-stdin.

Point the CLI at a different environment with IDAPT_API_URL. See API keys and scopes for scopes, version pinning, and spend caps.

Store the key as a CI secret and set IDAPT_API_KEY from it. Never commit a key or pass it as a plain command-line flag, where it can land in process listings and logs.

Where credentials live

The @idapt/cli package has no config file and no config command. Everything it needs comes from your login, the environment variables above, and the ambient context below.

Switch between accounts

The CLI can hold several signed-in accounts side by side, so a personal and a work account no longer take turns. Sign in again to add one, then switch whenever you like:

idapt auth list
idapt auth switch work

The account you are using carries its own workspace and agent selection, so switching accounts switches those too. Use --context work for a single command, or set IDAPT_CONTEXT for a whole shell.

idapt auth rename and idapt auth remove tidy the list. Removing the one you are using falls back to another rather than leaving you signed out of everything.

Set the workspace and agent you act as

Most commands run against a workspace. Rather than pass it every time, pin an ambient context that later commands inherit:

idapt workspace use <workspace-id>   # pin the active workspace
idapt workspace current              # show it
idapt workspace clear                # unset it

idapt agent use <agent-id>           # act as an agent
idapt agent current
idapt agent clear

To override the workspace for a single command, pass --workspace-id <id>. idapt whoami always shows who and where you are acting.

API keys and scopes

Create a key, choose its scopes, pin it to an API version, rotate it, and cap what it can spend.

Command reference

The idapt <resource> <verb> grammar, how to discover any command from the terminal, and the full command list.

Installing the CLI

Install, sign in, upgrade, and uninstall the idapt CLI on macOS, Linux, and Windows.

Up next

Command reference

The idapt <resource> <verb> grammar, how to discover any command from the terminal, and the full command list.

Was this helpful?