The DALP CLI (dalp) is a standalone command-line client for the Platform API. It ships as the package @settlemint/dalp-cli, and every business command it exposes calls the same public v2 endpoints documented in the DALP API reference.
Install
Install the package globally with the 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 --versionpnpm add --global @settlemint/dalp-cli
dalp --versionbun add --global @settlemint/dalp-cli
dalp --versionThe dalp command runs on one specific JavaScript runtime, which can differ from the one your package manager uses, and the package does not install it. Read the runtime and version from the package's engines field, install that runtime, and confirm it is on your PATH:
npm view @settlemint/dalp-cli engines
# example output: { bun: '1.4.4' }
bun --versionIf dalp -- reports that a program was not found, the runtime is missing or not on your PATH.
Run dalp -- to install the latest published version. In a terminal, dalp also prints a notice when a newer version exists. It checks the package registry at most once a day for that notice, and the NO_UPDATE_NOTIFIER environment variable or a CI environment switches the notice off.
The TypeScript SDK runs in browser, server and React Native applications on the runtime your application already uses. Use the CLI for terminal access to an instance, and the SDK when you build software.
Authenticate
Point the CLI at your instance, then sign in and confirm the session:
dalp config set apiUrl https://your-instance.example.com
dalp login
dalp whoamidalp login requests a device code and a short user code from the instance, then polls until you approve the request in the browser. When its output is a terminal and you pass no --format flag, it prints the verification URL and the user code and tries to open the URL. In agent mode the CLI does neither, so start the sign-in from a terminal without --format.
The Console shows its device approval screen at /auth/device. Enter the code shown in the terminal, or open the link that already carries it, and select Approve. If you have no Console session, the Console asks you to sign in first and returns you to that screen. A code the instance does not know, or that has expired, answers “That code is wrong or has expired. Check the code in your terminal and try again.” The user code has eight characters and expires after 10 minutes. The poll backs off when the instance asks it to slow down. It sends no token request once the code has expired and does not accept a token response that arrives after expiry. It stops with kit. if the code expires, and with kit. if you select Deny.
On approval, the CLI reads the session it was granted, requires that the session has an active organisation, asks for your wallet PIN and creates a new API key scoped read-write. The key is named dalp-cli with the hostname of the machine that created it, such as dalp-, expires after 90 days, and is stored locally. API key names hold at most 32 characters, so a hostname longer than 21 characters is cut to its first 20 and ends with …, as in dalp-. A session with no active organisation creates nothing and fails with kit.. After the CLI stores the key, it saves the instance URL as apiUrl and the organisation as defaultOrg in the global configuration file.
The scope and lifetime are fixed: dalp login offers no read-only or shorter-lived key, and the CLI reads no API key from the environment. For a CI job, a service or a read-only credential, create an API key as Authentication and API keys describes and call the API or the SDK with it.
Creating the key needs the same wallet verification as signing a transaction. The CLI asks for your wallet PIN on the terminal and does not echo it. To confirm with your authenticator app, your identity provider's authenticator or a recovery code instead, pass --, -- or --. An account that holds an authenticator must use its code, otp for a wallet authenticator or oidc-mfa for the identity provider's, because the platform refuses a PIN or recovery code for it with WALLET_. When standard input is not a terminal, set DALP_WALLET_CODE to the code. Without it the login stops with kit. after the approval and creates nothing.
Requests made with the key afterwards carry no wallet verification. The platform does not ask an API-key request for it, and refuses one only during the cooling-off period after a security change. The stored key therefore carries the signing authority of the account until it expires or is revoked.
During the cooling-off period after a security change, the login stops with WALLET_STEP_UP_HELD and keeps your stored credentials. A wrong code stops it with WALLET_STEP_UP_REJECTED. When your deployment requires two-factor sign-in and your account has not set it up, the browser approval succeeds and the CLI asks for the wallet code, but the platform refuses the key before it checks that code. The CLI prints Authorized, but the API key was not created with the code LOGIN_ and the reason Set up two-, and it stores no key. Set up two-factor sign-in on the Security page, then run dalp login again. Any other refusal of the key request stops with API_KEY_FAILED.
The CLI process never touches your password: you approve the short code inside your own browser, where you authenticate however your organisation normally requires. On approval the CLI briefly holds a short-lived session token. It sends that token as a bearer token only to read the session and to create the key, and every other account route refuses it. Those two routes accept a bearer token only from a device sign-in, so a token from a browser session cannot mint a key. The CLI never writes the session token to disk. When the Console signs in through an identity provider, only a Console session can approve a device code, and the Investor portal refuses device routes with DEVICE_.
The minted key is an ordinary API key, the same kind of secret a backend service holds, and once it is issued the platform treats it like a key created through the API key routes. It differs only in how it is made: a person's browser login creates it. Nothing binds it to the machine that stored it, so whoever holds the key can use it from any host until it expires after 90 days or is revoked under API keys in the Console.
The login step accepts only HTTPS instance URLs. HTTP is accepted for localhost, 127.0.0.1 and ::1 alone, for local development. A URL that is not absolute, or that carries embedded credentials, a query string or a fragment, is refused with kit.cli.INVALID_URL. There is no default instance. Without a URL from dalp login --, DALP_URL or the apiUrl config key, login stops with NO_URL.
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 logoutLogging out revokes this machine's API key on the server and then removes the stored credentials. When the instance does not confirm the revocation, the command removes the local credentials anyway and fails with kit., and the fix it prints is to revoke the dalp-cli key under API keys in the Console.
The CLI stores one credential set at a time, not several named identities you switch between. Re-running dalp login creates the new key, revokes the key that was stored before, and only then saves the new one. A key it cannot revoke is rolled back so the stored credentials still work, and that login fails with kit.. If the CLI cannot save the new credentials, it revokes the new key and fails with kit.. The previous key is already revoked by then, so run dalp login again. On Linux and Windows, separate identities on one machine mean separate config directories, set with the DALP_CONFIG_DIR environment variable. On macOS the keychain holds one login at a time, because saving a credential deletes every other account under the dalp-cli service name.
Active organisation
The API key that dalp login creates belongs to one organisation: the active organisation of the session that approved the login. Inspect it with the org command group:
dalp org list
dalp org switch <organizationId>
dalp org currentorg list lists only the organisation the stored key belongs to, because a key reads only its own organisation. org switch reads the stored key and accepts only the organisation that key belongs to. It saves that organisation in the stored credentials and in defaultOrg. Any other organisation id fails with a message that names the key's organisation, and the command saves nothing. A key cannot move to another organisation. To work in another organisation, run dalp login again so that the new key belongs to it. A key with no organisation also fails org switch. Run dalp login to replace it.
Configuration
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 listconfig get and config set both require the key argument, and an unknown key is refused with INVALID_CONFIG_KEY. config set always writes the global file, stores apiUrl and defaultOrg as typed, and refuses a format value other than toon, json, yaml or md. There is no bare dalp config get that dumps every key. Use dalp config list to see every stored and resolved value at once: it returns the global file's own values and the effective value after layering, so you can see which layer decides.
These keys are read by dalp login, dalp config and the other configuration-aware commands. They do not move an existing login: every other command talks to the instance URL and the organisation that dalp login stored, so to change where the CLI points, run dalp login against the new instance.
dalp login resolves its instance URL from three layers, each overriding the one before it:
- The global file at
~/.(override the directory with theconfig/ dalp/ config. json DALP_CONFIG_DIRenvironment variable). - A project file named
.dalprc.jsonin the current working directory. - The
DALP_URLenvironment variable, ordalp login --.url
Every request the CLI makes acts in the organisation the stored API key belongs to. defaultOrg, which the DALP_ORG environment variable also sets, records the organisation the login is for. It does not move a request to another organisation.
The CLI creates the config directory with mode 0700 and writes config.json with mode 0600. A configuration file that fails validation stops every command that reads it with kit.cli.CONFIG_INVALID, so fix or delete the file. Credentials are stored separately, as the next section describes.
Credential storage
The CLI stores your API key by operating system:
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. The file is not encrypted. Its permissions keep the key from other accounts on the machine, not from programs that run as you, such as an agent with a shell.
Neither storage path writes the credential to a shell history file or a log. On Linux and Windows the value is written straight to the file. On macOS it is handed to the system's security tool on its standard input, never as a command argument, so it does not appear in the process list while that tool runs. The tool reads each input line into a 4,096-byte buffer, so a sign-in whose email holds a line break, or whose credentials do not fit that buffer with the line break, fails with kit. and stores nothing.
Output format
Every command you run accepts --format to control how it prints results: toon, a compact text format and the default, or json, yaml, md, or jsonl for newline-delimited output. In agent mode, which means standard output is not a terminal or a --format flag is present, a generated command prints its progress events ahead of its result. With -- the output lists the events and then the response body: a JSON array, or, when the response links to resources the CLI can read, an object with numbered keys and a cta key. With -- each event and the result is its own chunk line, followed by a done line. Read the last numbered entry, or the last chunk line, before you pass the body to another program. A terminal run without --format prints only the result on standard output and sends progress to standard error.
The format config key accepts toon, json, yaml and md, and it is read by dalp config only: the installed CLI selects its output format from --format alone, so pass the flag on every command whose output a script parses. jsonl is a per-call format and is not a stored value.
Next steps
- 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
dalpfrom an MCP client or a coding agent's shell.