# Getting started

Source: https://docs.settlemint.com/docs/developers/developer-guides/cli/getting-started
Install the DALP CLI, connect it to a DALP instance, and verify your first authenticated command.



The DALP CLI (`@settlemint/dalp-cli`) gives operators and integrators terminal access to a DALP instance.

Use the CLI to authenticate through the browser, store a platform API key locally, and run asset and identity commands. For automation, the CLI can return machine-readable output for scripts or AI agents.

## Prerequisites [#prerequisites]

Before you start, you need:

* Node.js 20 or later, or Bun, on the machine where you run the CLI.
* The base URL of the DALP instance you want to manage.
* A user account that can sign in to that DALP instance and has access to the target organisation.

## Installation [#installation]

Install the CLI globally with npm:

```bash
npm install -g @settlemint/dalp-cli
```

Or install it globally with Bun:

```bash
bun add -g @settlemint/dalp-cli
```

After installation, the `dalp` command is available in your terminal.

## Configure the platform URL [#configure-the-platform-url]

The login command needs a DALP instance URL. You can pass it each time:

```bash
dalp login --url https://dalp.example.com
```

For repeated use, save the URL once:

```bash
dalp config set apiUrl https://dalp.example.com
dalp login
```

You can also set the URL for the current shell session:

```bash
export DALP_URL=https://dalp.example.com
dalp login
```

## Authenticate with device flow [#authenticate-with-device-flow]

The CLI uses the OAuth 2.0 Device Authorization Grant. You do not type your password into the terminal.

```bash
dalp login --url https://dalp.example.com
```

During login, the CLI:

1. Requests a device code from the DALP instance.
2. Opens the verification URL in your browser, or prints the URL and user code if the browser cannot open automatically.
3. Polls the DALP instance until you approve or deny the device request.
4. Uses the approved session to create a CLI API key.
5. Stores the API key locally for later commands.

The device code can expire before you approve it. If that happens, run `dalp login` again.

## Verify your session [#verify-your-session]

Run `whoami` after login:

```bash
dalp whoami
```

The command calls the authenticated user endpoint and returns the current user and active organisation. If no credentials are stored, authenticated commands fail with `NOT_AUTHENTICATED` and tell you to run `dalp login`.

## Credential storage [#credential-storage]

The CLI stores credentials differently by operating system:

| Platform          | Storage                           | Behaviour                                                                                            |
| ----------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------- |
| macOS             | System Keychain                   | Stores the API key under the `dalp-cli` service.                                                     |
| Linux and Windows | `~/.config/dalp/credentials.json` | Writes the credential file with `0600` permissions and refuses credentials with broader permissions. |

Logging out revokes the API key on the DALP instance and removes the local credentials:

```bash
dalp logout
```

## Configuration sources [#configuration-sources]

The CLI resolves configuration in this order:

| Priority | Source                | Example                                     |
| -------- | --------------------- | ------------------------------------------- |
| 1        | CLI flags             | `dalp login --url https://dalp.example.com` |
| 2        | Environment variables | `DALP_URL`, `DALP_ORG`                      |
| 3        | Project config        | `.dalprc.json` in the current directory     |
| 4        | Global config         | `~/.config/dalp/config.json`                |

Manage global configuration with `dalp config`:

```bash
# View all config
dalp config get

# View a single key
dalp config get apiUrl

# Set values
dalp config set format json
dalp config set defaultOrg my-org-slug
```

## Output formats [#output-formats]

Use `--format` when you need a specific output shape:

| Format | Flag            | Use case                                      |
| ------ | --------------- | --------------------------------------------- |
| `toon` | `--format toon` | Human-readable tables. This is the default.   |
| `json` | `--format json` | Machine-readable output for scripts and `jq`. |
| `yaml` | `--format yaml` | Configuration and review artifacts.           |
| `md`   | `--format md`   | Markdown reports.                             |

Set a default output format globally:

```bash
dalp config set format json
```

## First commands to run [#first-commands-to-run]

After login, start with read-only commands before running lifecycle actions:

```bash
# View your user profile and active organisation
dalp whoami

# List tokens in the system
dalp tokens list

# List users
dalp users list

# View system information
dalp system list

# Search across the platform
dalp search-results "bond"
```

Use `--format json` when you pipe the output into automation:

```bash
dalp tokens list --format json
```

## Next steps [#next-steps]

* [Command reference](/docs/developers/developer-guides/cli/command-reference) lists commands and options.
* [Scripting and automation](/docs/developers/developer-guides/cli/scripting) explains how to use the CLI in scripts and CI pipelines.
* [AI agent integration](/docs/developers/developer-guides/cli/ai-agents) explains how to use the CLI with LLMs, MCP servers, and AI coding agents.