Skip to content

Command-line interface

The CLI is the un-comtrade console script — installed alongside the Python package. Five outer commands, 22 sub-subcommands, and five output formats (json, table, csv, markdown, text).

Purpose

This page covers:

  1. The CLI entry point and global flags.
  2. The five outer commands.
  3. The output formats.
  4. Environment variables.
  5. Composing pipelines with shell pipes.

Prerequisites

  • un-comtrade-sdk installed (the un-comtrade script is on your PATH after install).
  • For authenticated endpoints, set UN_COMTRADE_KEY (see Authentication).

Walkthrough

Top-level help

un-comtrade --help

Usage: un-comtrade [OPTIONS] COMMAND [ARGS]...

  un-comtrade-sdk CLI.

Options:
  --output-format [json|table|csv|markdown|text]
  --help                          Show this message and exit.

Commands:
  metadata   Browse reference catalogues.
  trade      Fetch annual / monthly trade flows.
  analytics  Run typed analytics on a stored dataset.
  storage    Read / write / refresh storage backends.
  etl        Compose ETL pipelines.

Global flags

un-comtrade --output-format markdown metadata countries

The --output-format flag applies to every command. Default is json.

Metadata sub-commands

un-comtrade metadata countries
un-comtrade metadata partners
un-comtrade metadata hs-codes --level 2
un-comtrade metadata search "india"
un-comtrade metadata refresh

See CLI → Metadata for the full reference.

Trade sub-commands

un-comtrade trade exports --reporter 699 --period 2022 --partner 0
un-comtrade trade imports --reporter 699 --period 2022 --partner 0
un-comtrade trade balance --reporter 699 --period 2022
un-comtrade trade tariffline --reporter 699 --period 2022 --hs 854231

See CLI → Trade for the full reference.

Analytics sub-commands

un-comtrade analytics top-partners --input india_exports_2022.parquet --by exports --limit 5
un-comtrade analytics top-hs-codes --input india_exports_2022.parquet --hs-level 2 --limit 10
un-comtrade analytics global-balance --input india_exports_2022.parquet

See CLI → Analytics for the full reference.

Storage sub-commands

un-comtrade storage write --input exports.json --out india_exports.parquet
un-comtrade storage read --input india_exports.parquet
un-comtrade storage append --input history.parquet --from new.json
un-comtrade storage refresh --input india_exports.parquet

See CLI → Storage for the full reference.

ETL sub-commands

un-comtrade etl run --pipeline india_exports --stages fetch,export

See CLI → ETL for the full reference.

Examples

Compose a pipeline that fetches, exports, and reports:

un-comtrade trade exports --reporter 699 --period 2022 --partner 0 \
    --output-format json \
    | un-comtrade storage write --out india_exports_2022.parquet --from -

un-comtrade analytics top-partners \
    --input india_exports_2022.parquet \
    --by exports --limit 5 \
    --output-format markdown

A two-decade trend:

for year in $(seq 2010 2023); do
    un-comtrade trade exports --reporter 699 --period $year --partner 0 \
        --output-format json \
        | jq -r --arg y "$year" '"\($y): \(.aggregate_total | tonumber | . / 1e9)B USD"'
done

A Markdown report written to disk:

un-comtrade analytics top-partners \
    --input india_exports_2022.parquet \
    --by exports --limit 10 \
    --output-format markdown > report.md

The CLI is a thin wrapper around the Python facade — there is no separate CLI API surface.

Next steps