Install and configure the DALP CLI

OverviewCopy Anchor Link

The DALP CLI (dalp) is a standalone command-line client for the Platform API. It ships as the npm package @settlemint/dalp-cli, and every business command it exposes calls the same public v2 endpoints documented in Developer reference.

InstallCopy Anchor Link

The CLI is published to npm and installs globally with whichever package manager you already use. Run this once per machine, then confirm the install by printing the installed version:

npm install --global @settlemint/dalp-cli
dalp --version

pnpm add --global @settlemint/dalp-cli
dalp --version

bun add --global @settlemint/dalp-cli
dalp --version

The dalp command runs on the Bun runtime, so Bun has to be present on the machine even when npm did the installing. If dalp --version reports that bun was not found, install Bun and run it again. Nothing else about using the CLI depends on which package manager you chose.

The TypeScript SDK has no such requirement: it runs on Node 20 or later, on Bun, and in the browser. Reach for the CLI when you want a terminal against an instance, and for the SDK when you are building software.

AuthenticateCopy Anchor Link

Run dalp login to sign in. The CLI opens your browser against an OAuth 2.0 device authorization flow: it requests a device code and a short user code, opens the verification URL, and polls in the background until you approve the request in the browser. The poll backs off if told to slow down, and stops with a clear timeout if the code expires unconfirmed or you deny it. On approval, the CLI fetches your session and creates a new API key scoped read-write, then stores it locally.

The CLI process never touches your password: you approve the short code inside your own browser, where you authenticate however your organization normally requires. On approval the CLI briefly holds a short-lived browser session cookie, which it immediately trades for the durable API key it stores; the cookie itself is never written to disk. The minted key is an ordinary API key, the same kind of secret a backend service would hold, and the platform does not distinguish a CLI-minted key from one created directly through the API key routes once either is issued. What differs is provenance and lifecycle: the CLI's key is minted as a side effect of a human completing a browser login, and is expected to live in exactly one place, this machine's local credential store, for exactly one human.

The login step accepts only HTTPS instance URLs, with one exception: localhost, for local development. Point the CLI at a specific DALP instance before logging in, if you are not using the default.

dalp config set apiUrl https://your-instance.example.com
dalp login

Confirm the session at any time with dalp whoami. End it with dalp logout, which removes the stored credentials from this machine.

dalp whoami
dalp logout

Logging out deletes the stored key locally. It does not, by itself, revoke the key on the server, so if you are removing access after a compromise, revoke the key through the platform's own credential management as well as logging out locally. A lost or stolen laptop is therefore a server-side revocation event, not a local one.

The CLI stores one credential set at a time, not several named identities you switch between; re-running dalp login overwrites the stored session. Separate identities on one machine currently mean separate config directories, set with the DALP_CONFIG_DIR environment variable, not a profile switch the CLI manages for you.

Active organizationCopy Anchor Link

The API key that dalp login creates belongs to one organization: the active organization of the session that the login creates. The platform takes the organization from the key, not from a request header. Inspect it with the org command group:

dalp org list
dalp org switch <organizationId>
dalp org current

org switch reads the stored key and accepts only the organization that key belongs to. It saves that organization in the stored credentials and in defaultOrg. Any other organization id fails with a message that names the key's organization, and the command saves nothing. A key cannot move to another organization. To work in another organization, run dalp login again so that the new key belongs to it. A key with no organization also fails org switch; run dalp login to replace it.

ConfigurationCopy Anchor Link

The CLI resolves three configurable keys: apiUrl, defaultOrg, and format. Read and write them with:

dalp config get apiUrl
dalp config set defaultOrg <organizationId>
dalp config list

config get and config set both require the key argument; there is no bare dalp config get that dumps every key. Use dalp config list to see every resolved and stored value at once: it shows both the raw values the global config file holds and the effective, merged value after layering, so you can see which layer is actually deciding.

Configuration resolves from four layers, each overriding the one before it:

1. The global file at ~/.config/dalp/config.json (override the directory with the DALP_CONFIG_DIR environment variable).
2. A project file named .dalprc.json in the current working directory.
3. The DALP_URL and DALP_ORG environment variables.
4. Flags passed on the command line.

The global config file is created with restrictive 0700/0600 permissions on first write, before the CLI ever stores a credential in it.

Credential storageCopy Anchor Link

The CLI stores your API key differently depending on the operating system. On macOS it uses the system keychain, under the service name dalp-cli; on Linux and Windows it writes ~/.config/dalp/credentials.json with 0600 permissions.

On Linux and Windows, the CLI refuses to read a credentials file whose permissions have been loosened. It tells you to run chmod 600 on it, rather than silently trusting a world-readable file, because a shared machine can otherwise leak your API key to another account.

Neither storage path ever writes the credential to a shell history file or a log: the value only ever exists as a payload written directly to the store, never passed as a command-line argument.

Output formatCopy Anchor Link

Every command you run accepts --format to control how it prints results: toon (the compact default), json, yaml, md, or jsonl for newline-delimited streaming. Pick json or jsonl when you pipe CLI output into another program; jsonl also carries the incremental status events a long-running command emits while it waits for on-chain settlement.

Set a durable default instead of passing the flag every time:

dalp config set format json

Next stepsCopy Anchor Link

• CLI commands covers the generated command tree, how to discover a command you do not already know, and how to wait for on-chain settlement.
• Using the CLI with AI agents covers running dalp from an MCP client or a coding agent's shell.