CLI Guide

Query metrics, manage dashboards, and administer your semantic layer from the terminal. Works great with coding agents like Claude Code, Codex, and Devin.

The Metricly CLI provides command-line access to query metrics, manage dashboards, and administer your semantic layer directly from the terminal.

Installation

Using pip

pip install metricly-cli

Using uv (recommended)

uv tool install metricly-cli

Authentication

Metricly CLI uses Google OAuth for authentication. Your credentials are stored securely in ~/.metricly/.

Login

metricly login

This opens your browser for Google authentication. After authorizing, you'll be logged in and your credentials saved locally.

Opening browser for login...
✓ Logged in as user@company.com
ℹ Organization: acme-corp (admin)

Check current user

metricly whoami

Output:

┌─────────────────────────────┐
│       Current User          │
├─────────────────────────────┤
│ Email         user@company.com │
│ Organization  acme-corp        │
│ Role          admin            │
└─────────────────────────────┘

Logout

metricly logout

This clears all stored credentials from ~/.metricly/.

Switch organization

If you belong to multiple organizations:

# List your organizations
metricly org list

# Switch to a different org
metricly org switch other-org-id

Command Reference

Query Metrics

Execute metric queries against your data warehouse.

metricly query -m <metrics> [options]

Options: | Option | Short | Description | |--------|-------|-------------| | --metrics | -m | Metric names to query (required, repeatable) | | --dimensions | -d | Dimensions to group by (repeatable) | | --grain | -g | Time grain: day, week, month, quarter, year | | --start | | Start date (YYYY-MM-DD) | | --end | | End date (YYYY-MM-DD) | | --limit | | Maximum rows to return | | --order-by | | Column to sort by (append ' desc' for descending) | | --suggest-viz | | Include visualization suggestion | | --format | -f | Output format: table, json, yaml, csv |

Examples:

# Monthly revenue
metricly query -m total_revenue -g month

# Revenue by region, top 10
metricly query -m total_revenue -d region --limit 10 --order-by "total_revenue desc"

# Multiple metrics with date range
metricly query -m revenue -m order_count --start 2024-01-01 --end 2024-12-31

# Get visualization suggestion
metricly query -m total_revenue -g month --suggest-viz

# Output as JSON for scripting
metricly query -m revenue -d region --format json

Metrics Commands

Discover and manage metrics in your semantic layer.

List metrics

metricly metrics list
metricly metrics list --format json

Output:

┌──────────────────────────────────────────────────────┐
│                  Available Metrics                   │
├────────────────────┬─────────┬───────────────────────┤
│ name               │ type    │ description           │
├────────────────────┼─────────┼───────────────────────┤
│ total_revenue      │ simple  │ Sum of all revenue    │
│ order_count        │ simple  │ Count of orders       │
│ average_order_value│ derived │ Revenue per order     │
└────────────────────┴─────────┴───────────────────────┘

Show metric details

metricly metrics show total_revenue
metricly metrics show total_revenue --format yaml

Create a metric (admin only)

metricly metrics create metric.yaml

Example metric.yaml:

name: new_customers
type: simple
description: Count of new customers this period
type_params:
  measure: customer_count
filter: |
  {{ Dimension('is_first_order') }} = true

Update a metric (admin only)

metricly metrics update total_revenue updates.yaml

dbt owns computation, Metricly owns descriptive text. Editing description or label of an imported metric always works and survives the next manifest upload; editing a computation field (type, type_params, filter, measure, expr, metrics) of an imported metric is refused — make that change in the dbt repo instead. The same rule applies to metricly models update (computation fields entities, measures, dimensions, model, defaults, …). Every accepted edit lands on the learned trail with surface: api, so metricly learned undo can revert it.

Delete a metric (admin only)

metricly metrics delete old_metric
metricly metrics delete old_metric --yes  # Skip confirmation

Preview a metric before saving

Test a metric definition without persisting it:

metricly metrics preview metric.yaml
metricly metrics preview metric.yaml --limit 10 --grain week

Dimensions Commands

List available dimensions for grouping metrics.

metricly dimensions list
metricly dimensions list --format json

Dashboard Commands

Manage your Metricly dashboards.

List dashboards

metricly dashboards list

Output:

┌──────────────────────────────────────────────────────────────┐
│                        Dashboards                            │
├──────────────┬─────────────────┬────────────┬───────┬────────┤
│ id           │ title           │ visibility │ owner │ updated│
├──────────────┼─────────────────┼────────────┼───────┼────────┤
│ abc123       │ Sales Overview  │ org        │ you   │ 2h ago │
│ def456       │ My Dashboard    │ private    │ you   │ 1d ago │
│ ghi789       │ Team Metrics    │ org        │ alice │ 3d ago │
└──────────────┴─────────────────┴────────────┴───────┴────────┘

Show dashboard details

metricly dashboards show abc123
metricly dashboards show abc123 --format json

Create a dashboard

# Basic creation
metricly dashboards create "My New Dashboard"

# With description and visibility
metricly dashboards create "Team Metrics" -v org -d "Shared team dashboard"

Visibility options:

  • private - Only you can see it (default)
  • org - Shared with your organization

Delete a dashboard

metricly dashboards delete abc123
metricly dashboards delete abc123 --yes  # Skip confirmation

Add widget to dashboard

Add a new widget to an existing dashboard.

metricly dashboards add-widget <dashboard_id> --type <type> --title <title> -m <metrics> [options]

Options: | Option | Short | Description | |--------|-------|-------------| | --type | -t | Widget type: kpi, line_chart, bar_chart, area_chart, donut, table, heatmap | | --title | | Widget title (required) | | --metrics | -m | Metric names to query (required, repeatable) | | --dimensions | -d | Dimensions to group by (repeatable) | | --grain | -g | Time grain: day, week, month, quarter, year, or $grain | | --width | -w | Widget width in columns (1-10) | | --time-scope | | Date scope: range, latest, latest_complete | | --pivot-on | | Pivot dimension (table only): dimension values become columns | | --pivot-totals | | Show row/column totals in pivot table | | --page | | Page index (0-based, default: 0) | | --section | | Section index (0-based, default: 0) |

Examples:

# Add a KPI widget
metricly dashboards add-widget abc123 --type kpi --title "Revenue" -m total_revenue

# Add a line chart with time grain
metricly dashboards add-widget abc123 -t line_chart --title "Revenue Trends" -m revenue -g month

# Add a bar chart grouped by dimension
metricly dashboards add-widget abc123 -t bar_chart --title "Revenue by Region" -m revenue -d region

# Add a table with multiple dimensions
metricly dashboards add-widget abc123 -t table --title "Revenue by Region and Category" \
    -m revenue -d region -d category

Pivot Table Examples:

Pivot tables transform dimension values into columns for cross-tabulation views.

# Basic pivot: regions as columns, categories as rows
metricly dashboards add-widget abc123 -t table --title "Revenue by Region and Category" \
    -m revenue -d region -d product_category --pivot-on region

# Pivot with totals: monthly revenue by region
metricly dashboards add-widget abc123 -t table --title "Monthly Revenue by Region" \
    -m revenue -d region -g month --pivot-on region --pivot-totals

# Time-series pivot: show months as columns
metricly dashboards add-widget abc123 -t table --title "Revenue by Product per Month" \
    -m revenue -d product_category -g month --pivot-on metric_time --pivot-totals

Width defaults by type:

  • kpi: 2 columns (5 per row)
  • donut: 3 columns (3 per row)
  • heatmap: 5 columns (2 per row)
  • area_chart, line_chart, bar_chart, table: 10 columns (full width)

Semantic Models Commands (Admin)

Manage semantic models (data sources) in your semantic layer.

List models

metricly models list

Output:

┌────────────────────────────────────────────────────────┐
│                   Semantic Models                       │
├─────────────┬────────────────────────┬────────┬────────┤
│ name        │ description            │measures│ dims   │
├─────────────┼────────────────────────┼────────┼────────┤
│ orders      │ Order fact table       │ 5      │ 8      │
│ customers   │ Customer dimension     │ 2      │ 6      │
│ products    │ Product catalog        │ 3      │ 4      │
└─────────────┴────────────────────────┴────────┴────────┘

Show model details

metricly models show orders
metricly models show orders --format yaml

Create a model (admin only)

metricly models create model.yaml

Example model.yaml:

name: orders
description: Order fact table
model: ref('fct_orders')

defaults:
  agg_time_dimension: order_date

entities:
  - name: order_id
    type: primary
  - name: customer_id
    type: foreign

dimensions:
  - name: order_date
    type: time
    type_params:
      time_granularity: day
  - name: region
    type: categorical

measures:
  - name: revenue
    type: sum
    expr: amount
  - name: order_count
    type: count
    expr: order_id

Update a model (admin only)

metricly models update orders updates.yaml

Delete a model (admin only)

metricly models delete old_model
metricly models delete old_model --yes  # Skip confirmation

Manifest Commands (Admin)

Manage your organization's complete semantic layer manifest.

View manifest status

metricly manifest status

Output:

┌─────────────────────────────────────┐
│          Manifest Status            │
├─────────────────────────────────────┤
│ organization   acme-corp            │
│ project        acme_analytics       │
│ metrics        15                   │
│ models         5                    │
│ dimensions     32                   │
│ last_updated   2024-01-15 10:30:00  │
└─────────────────────────────────────┘

Export manifest

Export your semantic layer for backup or version control:

metricly manifest export -o manifest.yaml
metricly manifest export --output backup.json

Import manifest

Import metrics and models from a manifest file:

metricly manifest upload manifest.yaml

Field-level merge: Upload uses replace semantics — dbt owns computation (type, type_params, measures, entities, ...), Metricly owns descriptive text (description, label). The import result reports what happened at the field level so you can see what changed without re-diffing the manifest:

  • text_kept — a Metricly-edited text field was kept over the upload's diverging text for that item (a converged edit — upload text now matches — just clears silently and is not reported).
  • reconciled — a native (Metricly-created) item was deep-equal to an upload entry of the same name, so it was adopted as imported rather than reported as a conflict.
  • computation_overridden — a legacy computation edit on that item was dropped in favor of the upload's computation, since dbt always owns computation.
  • deleted_had_text_edits — an item absent from this upload was hard-deleted (replace semantics), but it still had a surviving Metricly text edit that is now gone; worth a second look before re-uploading.

Learned Trail Commands

See what Metricly learned for your org — corrections applied by the agent, CLI, MCP, or REST — and undo any of them. Read-only, attributed, reversible.

List what was learned

metricly learned list
metricly learned list --limit 10 --include-reverted
metricly learned list -f json

Each row shows id, when, who (the actor's email), surface (which interface acted — chat, mcp, cli, api), scope, summary, and reverted. A kind: proposal row (a computation change proposed but not written, for an imported entity) shows its summary with a (proposed, not applied) suffix and can never be reverted.

Show one entry

metricly learned show <id>

Prints the full entry, including before / after as YAML.

Undo an entry

metricly learned undo <id>
metricly learned undo <id> --yes
metricly learned undo --yes   # undoes your most recent reversible entry

Prompts for confirmation unless --yes is passed. Org-scope entries need admin/owner; personal (user-scope) entries can only be undone by their own author.

Output Formats

All commands support multiple output formats via --format / -f:

| Format | Description | Best for | |--------|-------------|----------| | table | Human-readable ASCII table (default) | Interactive use | | json | JSON output | Scripting, APIs | | yaml | YAML output | Config files | | csv | CSV output | Spreadsheets, data export |

Examples:

# Export query results to CSV
metricly query -m revenue -d region --format csv > report.csv

# Get dashboard as JSON for processing
metricly dashboards show abc123 -f json | jq '.pages[0]'

# Export metric definitions
metricly metrics list --format yaml > metrics.yaml

Common Workflows

Explore available data

# See what metrics exist
metricly metrics list

# See what dimensions you can group by
metricly dimensions list

# Understand how a metric is calculated
metricly metrics show total_revenue

Quick data exploration

# This month's revenue by region
metricly query -m total_revenue -d region -g month

# Top 10 customers by revenue
metricly query -m total_revenue -d customer_name --limit 10 --order-by "total_revenue desc"

# Daily trend for the last 30 days
metricly query -m total_revenue -g day --start 2024-01-01 --end 2024-01-31

Export data for reporting

# Export to CSV
metricly query -m revenue -m orders -d region -g month \
  --start 2024-01-01 --end 2024-12-31 \
  --format csv > quarterly_report.csv

# Export to JSON for further processing
metricly query -m revenue -d product_category --format json > data.json

Manage semantic layer (admin)

# Export current state
metricly manifest export -o manifest_backup.yaml

# Create new metric
metricly metrics preview new_metric.yaml  # Test first
metricly metrics create new_metric.yaml   # Then create

# Import updated manifest from dbt project
metricly manifest upload path/to/manifest.yaml

Troubleshooting

"Not logged in" error

metricly login

"Token expired" error

Your refresh token may have expired. Re-authenticate:

metricly logout
metricly login

"Permission denied" error

Some operations require specific roles:

  • Viewer: Can query metrics and view dashboards
  • Member: Can create and manage their own dashboards
  • Admin: Can manage metrics and semantic models
  • Owner: Full access including organization settings

Contact your organization owner to request elevated permissions.

Connection issues

  1. Check your internet connection
  2. Verify the Metricly API is accessible
  3. Check firewall settings if in a corporate network

Invalid metric/dimension names

# List available metrics
metricly metrics list

# List available dimensions
metricly dimensions list

Use exact names as shown in the list output.

Environment Variables

| Variable | Description | |----------|-------------| | METRICLY_API_URL | Override API endpoint (for self-hosted) | | METRICLY_CONFIG_DIR | Override config directory (default: ~/.metricly) |

Configuration Files

Credentials and config are stored in ~/.metricly/:

~/.metricly/
├── credentials.json    # OAuth tokens (encrypted)
└── config.json         # User preferences

These files have restricted permissions (0600) and should not be shared.

Next Steps

MCP Server Setup

Connect the CLI to AI assistants like Claude, ChatGPT, and Cursor.