ePrivacy and GPDR Cookie Consent by Cookie Consent Skip to main content

Getting Started with the Customer Data Platform Command-Line Tool

CDP CLI is a command-line tool that gives you fast, read-only access to data in your Meiro CDP environment.

It is designed for users who need to inspect data, validate setup, troubleshoot issues, or run quick checks without navigating through the web interface.

Because the tool is read-only, it is safe for analysis work. It does not create, update, or delete CDP records.

Who Is CDP CLI For?

CDP CLI can be useful for:

  • Technical support teams

  • QA engineers

  • Analysts

  • Consultants

  • Implementation teams

  • Developers

  • Advanced platform users

You do not need to be a developer to use it, but basic terminal knowledge is helpful.

Why Use CDP CLI?

Using the CLI can save time when you need quick answers.

Common use cases

  • Check whether data is arriving into CDP

  • Search for a specific customer profile

  • Validate segment setup

  • Review exports and logs

  • Compare multiple environments

  • Troubleshoot authentication or integration issues

  • Run repetitive daily checks faster than through UI

Before You Start

Prepare the following:

  • Access to the CDP CLI repository

  • Your CDP environment URL
    Example: https://cdp.client-example.com

  • Your login email and password

  • Terminal access on:

    • macOS

    • Linux

    • Windows (WSL recommended)

Install CDP CLI

Requires GitHub CLI installed:

gh api repos/meiroio/cdp-cli/contents/setup-cli.sh -H "Accept: application/vnd.github.raw" | bash

Alternative Option

uv tool install "git+https://github.com/meiroio/cdp-cli.git"

If the Command Is Not Found

If your terminal does not recognize cdp, add the local tools path:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

First-Time Setup

Setup usually takes only a few minutes.

Step 1: Save Your Environment

This creates a reusable alias for your CDP environment.

cdp instance set demo \

  --url https://cdp.client-example.com \

  --email you@company.com \

  --password 'your-password'

In this example:

  • demo = name of the saved connection

  • URL = your CDP environment

  • email/password = your login credentials

You can choose any alias name, such as prod, staging, or client-a.

Step 2: Log In

cdp auth login --instance demo

This creates an authenticated session.

Step 3: Verify Access

cdp auth status --instance demo --check

Use this command to confirm that authentication is working correctly.

Step 4: Run Your First Check

cdp customers count --instance demo

This returns the number of customer profiles in the selected environment.

Working with Multiple Environments

Many teams use several environments such as production, staging, or testing.

View Saved Environments
cdp instance list
Switch Active Environment
cdp instance use demo
Show Current Configuration
cdp instance show --instance demo

How Commands Work

CDP CLI commands follow a simple structure:

cdp <area> <action> [options]
Examples
cdp segments list
cdp customers search --query "john"
cdp reports list

Think of:

  • area = what you want to work with

  • action = what you want to do

Use Cases

This section shows real-life examples of how you can use CDP CLI in your daily work.

Each example is based on common tasks in Meiro CDP (Profiles, Segments, Channels, Journeys, Administration, Diagnostics).

You don’t need to learn all commands — just find the situation that matches what you are trying to solve.

Daily Data Pipeline Health Check

When to use: At the start of the day, or whenever you want to quickly confirm that data is still flowing into CDP.

What does this help you answer:

  • Are new customers still coming in?

  • Are events still being tracked?

  • Did any data source stop sending data?

What to run:

cdp customers count --instance demo
cdp customers per-date --instance demo
cdp customers per-source --instance demo
cdp customers last-update --instance demo
cdp events per-date --instance demo
cdp events last-times --instance demo

What you get:

A quick overview of data volume and freshness.
If numbers suddenly drop or stop updating, it usually means there is a data pipeline issue.

Investigate a Customer Issue

When to use: 

When support asks something like: “Why is this customer missing from a campaign or segment?”

What this helps you answer:

  • Does the customer exist?

  • What data do we have about them?

  • Are they part of the expected segment?

  • Did any events happen?

What to run

What you get

A full customer profile view, which helps you quickly identify what is missing or incorrect.

Find a Customer by Exact Identifier

When to use:

When you know exactly what you are looking for (for example email, phone, or external ID).

What to run:

cdp customers search-attribute --instance demo --attribute-id mx_email --query "john@example.com"

What you get:

A precise match with minimal noise.

Validate Segment Behavior and Exports

When to use:

  • A segment looks correct in UI

  • But something feels wrong (missing users, export not working, etc.)

What does this help you answer:

  • Is the segment configured correctly?

  • Has it changed recently?

  • Did exports run successfully?

What to run:

cdp segments list --instance demo --limit 50
cdp segments get --instance demo --segment-id 123
cdp segments history --instance demo --segment-id 123
cdp segments exports --instance demo --segment-id 123
cdp segments export-logs --instance demo --segment-id 123 --export-id 1 --limit 20

What you get:

A clear view of segment setup, history, and export activity.

Review Campaigns Across Channels

When to use:

Before release, during QA, or when reviewing campaign setup.

What does this help you answer:

  • Are campaigns created correctly?

  • Are exports triggered?

  • Do all channels have activity?

What to run:

cdp emails list --instance demo --limit 50
cdp push-notifications list --instance demo --limit 50
cdp whatsapp list --instance demo --limit 50

What you get:

A quick overview of campaigns across Email, Push, and WhatsApp.

Check Channel Configuration

When to use:

When a channel behaves unexpectedly (for example emails not sending).

What does this help you answer

  • Is the channel configured correctly?

  • Are the required settings present?

What to run:

cdp channels list --instance demo
cdp channels get --instance demo --channel-type emails
cdp channels email-addresses --instance demo

What you get

A clear view of channel configuration and readiness.

Validate Journey or Funnel Setup

When to use:

When journeys or funnels exist, but results don’t match expectations.

What does this help you answer:

  • Is the structure correct?

  • Are nodes configured properly?

  • Do statistics look reasonable?

What to run:

cdp journeys list --instance demo --limit 50
cdp journeys get --instance demo --journey-id <journey_uuid>
cdp journeys statistics --instance demo --journey-id <journey_uuid>

What you get

Basic validation of journey structure and performance.

Troubleshoot Identity Stitching

When to use:

  • Duplicate profiles

  • Missing merges

  • Unexpected identity behavior

What to run:

cdp stitching list --instance demo
cdp stitching rules --instance demo --category-id stitching_email
cdp customers stitching-graph --instance demo --customer-id <customer_uuid>

What you get:

Insight into how identities are connected and why profiles may or may not merge.

Check User Activity and Permissions

When to use:

For audits, troubleshooting access issues, or reviewing team activity.

What to run:

cdp users list --instance demo
cdp users roles --instance demo
cdp users activity --instance demo

What you get:

Overview of users, roles, and recent activity.

Check Diagnostics (Processing Issues)

When to use:

When data processing is delayed, or something seems “stuck”.

What to run:

cdp api get --instance demo --path /api/debugger/metrics
cdp api get --instance demo --path /api/debugger/errors

What you get:

Low-level diagnostics data, even if it is not available in the UI.

Run Real-Time Checks (WBS)

When to use:

During live troubleshooting or support calls.

What does this help you answer:

  • Does the profile exist right now?

  • Is the user in the correct segment?

  • Is the user subscribed?

What to run:

cdp wbs profile --instance demo --attribute email --value user@example.com
cdp wbs segments --instance demo --attribute email --value user@example.com
cdp wbs email-subscription --instance demo --email-address user@example.com

What you get:

Real-time view of customer data and state.

Compare Environments (Staging vs Production)

When to use:

When something works in one environment but not in another.

What to run:

cdp instance list
cdp instance use staging
cdp customers count

cdp instance use prod
cdp customers count

What you get:

Quick comparison using the same commands across environments.

Main Command Groups

CDP CLI commands are organized into groups based on what you want to check or manage.

Command Area

Purpose

instance

Manage saved environments

auth

Login and token handling

customers

Search profiles and counts

segments

Audiences and exports

attributes

Schema and history

events

Event metrics

emails, push-notifications, whatsapp

Channel objects

journeys

Journey automation

channels

Channel settings

users

Users and roles

reports

Reporting objects

api get

Direct GET endpoint access

Important Things to Know

  1. Read-Only by Design: CDP CLI is intended for safe data access. It does not modify records.
  2. Automatic Re-Authentication: If your session expires, the tool can automatically attempt:
      1. Token refresh
      2. Login using stored password

  3. Saved Configuration Location: Your saved environments are typically stored in:~/.config/cdp-cli/instances.json

  4. Different ID Types: Some commands require different ID formats.

    1. Numeric IDs

      1. Examples:

          1. segment IDs

          2. export IDs

          3. tag IDs

    2. Text IDs

      1. Examples:

        1. mx_email

        2. web

    3. UUID IDs: Long unique identifiers used by some objects.

       

Troubleshooting

cdp: command not found

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Environment Not Found

cdp instance set demo --url https://... --email you@company.com --password '...'

Token Expired

cdp auth refresh --instance demo
cdp auth login --instance demo

Unexpected Errors

Check:

  • correct environment selected

  • valid login credentials

  • correct ID type used

  • access permissions

  • network connectivity

Getting Help

Show All Commands

cdp --help

Show Help for a Specific Area

cdp customers --help
cdp segments --help

Best Practices

  • Save separate aliases for each environment

  • Use clear names like prod, stage, demo

  • Verify environment before running checks

  • Use search commands before deeper investigation

  • Prefer CLI for repetitive validation tasks

  • Keep credentials secure

Summary

CDP CLI is a fast and safe way to inspect your Meiro CDP environment from the terminal.

It is especially useful for support, QA, analytics, and technical operations teams who need quick answers without navigating the UI.

No Comments
Back to top