Profiles & configuration

pdcli stores settings per profile. Each profile has its own company domain, auth mode, and stored credentials, so you can keep several Pipedrive accounts side by side. The active profile defaults to default.

Profiles

Create a profile by logging in with --profile; the name is created on first use:

pdcli auth login --profile work
pdcli auth login --profile personal

List, switch, and inspect the active profile:

pdcli profile list

* default (authenticated)
  work (authenticated)
  personal (authenticated)

The * marks the active profile.

pdcli profile use work        # switch the active profile
pdcli profile current         # print the active profile name

Run a single command against another profile without switching — the global --profile flag works on every command:

pdcli deal list --profile work

Per-profile config

config get/set/list operate on the active profile (or the one named with --profile):

pdcli config set company_domain acme
pdcli config set default_output json
pdcli config get company_domain
pdcli config list
pdcli config unset default_output     # remove a key from the active profile

company_domain=acme
auth_mode=token
default_output=json

config set default_output validates the value — it must be table, json, yaml, or csv, otherwise the command exits 64 and lists the accepted formats.

Common keys:

| Key | Set by | Purpose | | --- | ------ | ------- | | company_domain | auth login | The acme in acme.pipedrive.com; builds the API host. | | auth_mode | auth login | token or oauth. | | default_output | you | Default output format when no --output flag is given. |

Credentials (the token, or the OAuth bundle) are never in config — they live only in the OS keychain.

Aliases

Save a frequently typed command as a short alias, then invoke it by name:

pdcli alias set wd "deal list --status won"
pdcli alias list
pdcli alias unset wd

Aliases are stored globally, not per profile — they’re shared across every profile. A name that would shadow a real pdcli command is refused (exit 64), so an alias can never mask a built-in.

Aliases execute with your full credentials and can wrap destructive commands (api DELETE, merge) — review aliases in shared configs before running them. Alias writes are not safe under concurrent pdcli invocations sharing one config (last write wins).

Precedence

For any setting, the most specific source wins:

command-line flag  >  environment variable  >  profile config

So PDCLI_COMPANY_DOMAIN=acme pdcli deal list overrides the profile’s company_domain, and PDCLI_API_TOKEN overrides the keychain token for that run. (The --company and --api-token flags exist only on pdcli auth login, where they take precedence over the environment.)

Environment variables

| Variable | Effect | | -------- | ------ | | PDCLI_COMPANY_DOMAIN | Company subdomain (acme). Overrides profile config. | | PDCLI_API_TOKEN | Personal API token. Used instead of the keychain; no keychain needed. | | PDCLI_PROFILE | Active profile name (same as --profile). | | PDCLI_CLIENT_ID | OAuth app client ID, read by auth login --oauth. | | PDCLI_CLIENT_SECRET | OAuth app client secret, read by auth login --oauth. | | PDCLI_CONFIG_DIR | Override the config-store directory — isolates profiles for tests, CI, or sandboxes so a run never touches your real profiles. Defaults to the OS config path. | | PDCLI_BASE_URL | Point pdcli at a localhost mock endpoint instead of the live host. Host-locked to localhost/127.0.0.1/::1 and requires PDCLI_API_TOKEN. See Local mock endpoint. | | NO_COLOR | Any value disables colored output (same as --no-color). |

Together, PDCLI_COMPANY_DOMAIN + PDCLI_API_TOKEN are all you need for a fully non-interactive, keychain-free run — ideal for CI and agents:

PDCLI_COMPANY_DOMAIN=acme PDCLI_API_TOKEN=$TOKEN pdcli deal list --output json