Scripting and automation

The DALP CLI gives operators a repeatable command-line control plane for scripts, CI jobs, and local AI assistants. Use the CLI for work a responsible user could run in a terminal: checking platform state, reading token or identity data, running setup commands, and collecting evidence for an operational workflow.

Use the REST API, TypeScript SDK, OpenAPI specification, or MCP tools when another integration style fits the job better. The difference is interface and runtime. Each path still uses DALP authentication, organisation context, and validation.

Choose the right automation surface

• Use the CLI for shell scripts, CI jobs, operational checks, setup tasks, and local automation. Authenticated commands use the instance saved by dalp login. Start with CLI getting started.
• Use the REST API when a backend service or external workflow calls DALP directly. Authenticate with an API key in the X-Api-Key header, or with a browser session cookie where session-based authentication applies. Start with API getting started.
• Use the TypeScript SDK when a TypeScript service needs typed DALP calls without hand-writing HTTP requests. Configure the generated client with an API key. Start with the SDK guide.
• Use the OpenAPI specification when you need the route contract, API-tool imports, or generated clients in another language. The OpenAPI routes use the same authentication model as the API route you call. Start with the API reference and OpenAPI specification.
• Use MCP tools when an AI assistant supports MCP and should call typed DALP tools instead of parsing shell output. MCP uses the authenticated CLI session that registers the MCP server. Start with CLI AI agent integration.

A good rule is simple: use the CLI for scripts that operate like a responsible user at a terminal. Use the API or SDK for services, application traffic, generated clients, or jobs that should not depend on an interactive CLI login.

Return machine-readable output

Set --format json on commands that feed another tool:

# Per command
dalp tokens list --format json

# Or set a default output format
dalp config set format json

The CLI configuration supports toon, json, yaml, and md output formats. Prefer JSON for automation because it is stable to parse with tools such as jq.

Pipe JSON to jq

# Get all token addresses
dalp tokens list --format json | jq -r '.data[].address'

# Get the first admin wallet in an admin listing
dalp users admin-list --format json | jq -r '.data[0].wallet'

# Count tokens by type
dalp tokens list --format json | jq '.data | group_by(.type) | map({type: .[0].type, count: length})'

Keep parsing logic close to the command it supports. That makes it easier to review which DALP field the automation depends on before it is promoted to a CI runner or runbook.

Configure scripts by environment

Use DALP_URL to tell unauthenticated setup commands which DALP instance to target:

export DALP_URL=https://your-platform.example.com
dalp login

For authenticated commands, the CLI uses the DALP instance and active organisation saved by dalp login and later authentication commands. Setting DALP_URL after login does not retarget an existing saved credential. If a runner must operate against another DALP instance, log in to that instance first.

Use dalp auth org-switch when automation must change the active organisation for authenticated commands:

dalp auth org-switch "org_..." --format json

Use a project .dalprc.json for non-secret team defaults such as the target instance and output format:

{
  "apiUrl": "https://staging.example.com",
  "format": "json"
}

The CLI resolves configuration from global config, project config, environment variables, and command overrides. Treat .dalprc.json as a checked-in convenience file for non-secret settings only, not as the way to change the active organisation for authenticated commands. Do not put API keys, passwords, session tokens, or private wallet material in project configuration.

Handle CLI credentials safely

Run dalp login before calling authenticated command groups such as tokens, users, identities, auth, monitoring, or system.

The CLI keeps saved login material outside project configuration. On macOS it uses Keychain.

On Linux and other non-macOS runners, the CLI writes a permission-protected login file under the DALP config directory.

If file permissions are too open, the CLI rejects the credential file and asks you to restrict it to the current user.

Do not copy credential files between runners.

For CI, choose one login pattern. Document who owns it.

• keep a self-hosted runner logged in for CLI-only jobs
• create an API key when a REST API or SDK integration needs its own credential
• store API keys only in your CI secret store

# Create an API key from an authenticated CLI session
dalp auth api-key-create "ci-pipeline" --format json

The returned secret value is sensitive. Copy it directly to the secret manager for the integration that needs it, then treat it as unrecoverable secret material.

Write scripts that fail clearly

Use standard shell safety settings and check authentication before running a mutating workflow:

#!/usr/bin/env bash
set -euo pipefail

if ! dalp whoami --format json > /dev/null 2>&1; then
  echo "Not authenticated. Run: dalp login" >&2
  exit 1
fi

dalp tokens list --format json

DALP CLI errors include a stable error code where one is available, followed by human-readable Why: and Fix: lines. Scripts should fail on non-zero exits and send the full CLI error output to logs visible to the operator.

For example, an authenticated command without a saved login returns NOT_AUTHENTICATED, tells the operator to run dalp login, and explains that no stored DALP credentials were found for the command. Do not hide that message behind a generic command failed wrapper.

Mutation review gate

Print the target, input file, and approval step before a regulated asset mutation runs.

#!/usr/bin/env bash
set -euo pipefail

TOKEN_ADDRESS="$1"
RECIPIENTS_FILE="$2"
APPROVAL_REF="${3:-manual-approval-required}"

printf 'token=%s\nrecipients=%s\napproval=%s\n' \
  "$TOKEN_ADDRESS" "$RECIPIENTS_FILE" "$APPROVAL_REF" >&2

if [[ "$APPROVAL_REF" == "manual-approval-required" ]]; then
  echo "Provide an approval reference before minting." >&2
  exit 1
fi

Keep the approval record outside the script when your operating procedure requires a four-eyes review. Log the approval reference. Do not make the shell decide whether the business approval is valid.

Example: read token state in a script

This read-only script is safe to use as a starting point for runbooks because it only inspects state and writes a small summary to standard output:

#!/usr/bin/env bash
set -euo pipefail

TOKEN_ADDRESS="$1"

token_state=$(dalp tokens read "$TOKEN_ADDRESS" --format json)
holder_count=$(dalp tokens holders "$TOKEN_ADDRESS" --format json | jq '.meta.total')

echo "$token_state" | jq --argjson holderCount "$holder_count" '{
  name: .data.name,
  symbol: .data.symbol,
  holderCount: $holderCount
}'

Keep mutating workflows more conservative. Review the command reference for required arguments before running the script.

Record the operator approval step outside the script where your process requires it. Log the request and response identifiers that matter for auditability.

Example: batch mint from CSV

Use explicit inputs and let the shell stop on the first failed mint. The example skips blank rows. Failed DALP calls stop the remaining mints instead of continuing silently.

#!/usr/bin/env bash
set -euo pipefail

TOKEN_ADDRESS="$1"
RECIPIENTS_FILE="$2"  # CSV: wallet,amount

while IFS=, read -r wallet amount; do
  if [[ -z "$wallet" || -z "$amount" ]]; then
    continue
  fi

  echo "Minting $amount to $wallet..."
  dalp tokens mint \
    --address "$TOKEN_ADDRESS" \
    --to "$wallet" \
    --amount "$amount" \
    --format json
done < "$RECIPIENTS_FILE"

For regulated asset operations, keep the approval workflow, signer controls, and reconciliation checks in your operating procedure.

The CLI executes the DALP command you run. It does not replace your organisation's approval policy.

Use the CLI in pipelines

A self-hosted runner can run CLI jobs when it already has a DALP login credential for the target instance:

name: DALP operational check
on:
  workflow_dispatch:

jobs:
  check:
    runs-on: [self-hosted, linux]
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: "22"

      - name: Install DALP CLI
        run: npm install -g @settlemint/dalp-cli

      - name: Verify the runner login and read token list
        run: |
          dalp whoami --format json > /dev/null
          dalp tokens list --format json | jq '.data | length'

Use this pattern for operational checks, evidence collection, and controlled maintenance tasks.

For application deployments or jobs that cannot keep a CLI login credential, use the REST API or TypeScript SDK with an API key stored in your CI secret manager.

Production checklist

Before promoting a CLI script to a shared runner or runbook, check these controls.

• target instance and organisation
• JSON output
• no committed credentials
• fail-fast shell settings
• clear failure logs
• approval and reconciliation steps
• command reference links

Related

• CLI getting started
• CLI command reference
• CLI AI agent integration