@tallistr/cli

v0.0.12

Published

10 days ago

Tallistr CLI — CO2e emission tracking for developers, CI, and LLM agents

0High
0Medium
0Low

niklaserik

tallistr co2e emissions cli mcp

@tallistr/cli

Command-line interface for querying Tallistr climate-accounting data, managing organizational context, and integrating with LLM agents via MCP.

Built by Tallistr AB (tallistr.com), this package helps companies operationalize climate accounting across receipts, suppliers, vouchers, reports, and business travel with developer-friendly automation.

Tallistr turns operational finance and travel activity into explainable CO2e calculations. The CLI is the easiest way to ask questions such as “how much did we emit?”, “which suppliers drive the most spend or CO2e?”, and “why was this receipt calculated this way?” from a terminal, a script, CI, or an LLM workflow.

Use @tallistr/cli when you want to:

Track emissions by scope, category, supplier, and period
Explain how specific receipts and vouchers were calculated
Standardize reporting workflows in scripts and CI pipelines
Power AI-assisted workflows with predictable machine-readable outputs

Typical questions the CLI can answer:

“How much did our group emit this year, and which scope dominates?”
“Which legal entity or company accounts for the largest share of emissions?”
“Which suppliers drive the most spend or CO2e?”
“Which receipts mention a certain supplier, route, invoice number, or reference?”
“Why did Tallistr classify this receipt into this category and CO2e value?”

Organizational Model

Tallistr uses two key concepts throughout CLI and MCP:

Tenant: a Tallistr workspace, usually representing a group of companies or a parent organization
Legal Entity: one company inside that tenant, for example Tallistr AB

In practice:

Choose a tenant when you want to ask questions at group/workspace level.
Add a legal entity filter when you want to narrow those questions to one company.

If no legal entity is set, most queries answer for the whole tenant.

AI assistants and MCP clients should follow the Tallistr MCP normal analysis workflow for deterministic context selection, analytical defaults, and evidence handling.

Installation

npm install -g @tallistr/cli
# or
pnpm add -g @tallistr/cli

After installation, the tallistr command is available globally.

Quick Start

# 1. Authenticate (opens browser for PKCE, or use device code)
tallistr auth login --browser
tallistr auth login              # device flow — no browser needed

# 2. Select your tenant (auto-selects if you only have one)
tallistr tenant list
tallistr tenant use <tenantId-or-name>

# 3. Query emissions
tallistr emissions summary
tallistr emissions drilldown --format json

# 4. Verify everything works
tallistr doctor

Authentication

The CLI supports three authentication methods. Production discovers the active provider from the Tallistr API and currently resolves to Better Auth at https://api.tallistr.com/auth/better-auth. Do not set TALLISTR_ISSUER_URL for normal production use; explicit issuer overrides are reserved for local and staging verification. The provider lifecycle is tracked in the authentication documentation.

Browser Flow (PKCE) — Recommended

Opens your default browser to sign in through the configured Tallistr OAuth issuer. Production resolves to Better Auth. The flow is secure, human-friendly, and does not require copying codes.

tallistr auth login --browser
# → Opens browser → sign in → redirects back → authenticated ✓

A temporary local HTTP server listens on a random port for the OAuth callback. The browser flow times out after 120 seconds if not completed.

Device Authorization Flow — Headless

For environments without a browser (SSH sessions, containers, CI runners with user interaction). Displays a code to enter at a URL on any device.

The Better Auth issuer provisions the public CLI client ID, binds it to TALLISTR_API_URL, and supports both device authorization and browser PKCE. During staging verification, set both TALLISTR_API_URL and TALLISTR_ISSUER_URL to their staging values. Normal production use requires no issuer override.

$ tallistr auth login
Starting Device Authorization flow...

  User code:        ABCD-1234
  Verification URL: https://api.tallistr.com/auth/better-auth/device

Open the URL above in your browser and enter the code.
Waiting for authentication...
Authenticated successfully.

Token Override — CI/CD

Set TALLISTR_TOKEN to bypass interactive auth entirely. Useful for pipelines, scripts, and automated systems.

export TALLISTR_TOKEN="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
tallistr emissions summary  # uses the token directly, no login needed

Managing Auth State

tallistr auth status   # Show current auth state, token source, expiry
tallistr auth logout   # Clear stored credentials and config

Rate Limits

Tallistr APIs can return HTTP 429 when a script or batch workflow sends too many requests for the same credential in a short period. The CLI SDK retries 429 responses with exponential backoff and preserves Retry-After metadata on the final rate-limit error so automation can pause before retrying.

For large loops, prefer batching work at the script level and pause when the API returns Retry-After. Avoid running many parallel CLI processes with the same token unless the workflow can tolerate 429 responses.

Commands

`tallistr tenant list`

List all tenants accessible to the authenticated user. When only one tenant is available and no default is configured, it is auto-selected as the default.

$ tallistr tenant list
Tenant ID                              Name
────────────────────────────────────── ─────────────
00000000-0000-0000-0000-000000000001   Tallistr Group

ℹ Auto-selected tenant "Tallistr Group" as default (only tenant available).

`tallistr tenant use <id-or-name>`

Set the default tenant for all subsequent commands. You can pass a tenant UUID, or an exact tenant name.

$ tallistr tenant use 00000000-0000-0000-0000-000000000001
Default tenant set to 00000000-0000-0000-0000-000000000001

$ tallistr tenant use "Tallistr Group"
Default tenant set to Tallistr Group (00000000-0000-0000-0000-000000000001)

`tallistr legal-entity list`

List legal entities within the current tenant.

$ tallistr legal-entity list
Legal Entity ID                        Name                 Country
────────────────────────────────────── ──────────────────── ───────
11111111-1111-1111-1111-111111111111   Tallistr AB          SE
22222222-2222-2222-2222-222222222222   Tallistr AS          NO

`tallistr legal-entity use <id>`

Set the default legal entity filter. Once set, emission queries are scoped to this entity.

$ tallistr legal-entity use 11111111-1111-1111-1111-111111111111
Default legal entity set to 11111111-1111-1111-1111-111111111111

`tallistr emissions summary`

Use this when you want a fast answer to “how much did we emit?” or “which scope/category is largest?”.

# Default table output
$ tallistr emissions summary

# Filter by date range and scope
$ tallistr emissions summary --from-date 2025-01-01 --to-date 2025-06-30 --scope 3

# Machine-readable JSON
$ tallistr emissions summary --format json

# Pipe-friendly NDJSON
$ tallistr emissions summary --format ndjson | jq '.totalCo2eKg'

`tallistr emissions drilldown`

Use this when you want to move from a summary into the detailed records behind it.

# Default view (first 100 items)
$ tallistr emissions drilldown

# Paginate through results
$ tallistr emissions drilldown --limit 500 --offset 0

# Filter by category
$ tallistr emissions drilldown --category "Business Travel"

# Stream as NDJSON for large datasets
$ tallistr emissions drilldown --format ndjson --limit 10000

`tallistr explain <id>`

Use this when you want an audit trail for a specific receipt or voucher. It explains the calculation and auto-detects the resource type from the UUID.

# Explain how a receipt's CO2e was calculated
$ tallistr explain 12345678-1234-1234-1234-123456789012

# JSON output for programmatic use
$ tallistr explain 12345678-1234-1234-1234-123456789012 --format json

`tallistr supplier list`

Use this when you want to see the normalized supplier master data Tallistr recognizes for the current tenant.

tallistr supplier list
tallistr supplier list --limit 50 --offset 100
tallistr supplier list --format csv > suppliers.csv

# Filter by name fragment (case-insensitive ILIKE on canonical supplier name)
tallistr supplier list --search acme

`tallistr supplier search <query>`

Use this when you only remember a fragment of a supplier name (for example acme or travel) and want to find the matching canonical suppliers. Mirrors supplier list --search <query> and accepts the same pagination and output flags.

tallistr supplier search acme
tallistr supplier search "uber" --limit 10
tallistr supplier search travel --format json

`tallistr sourcing kpis`

Use this when the question is spend-oriented, for example “what does our sourcing profile look like?” rather than emissions-oriented.

tallistr sourcing kpis --base-currency SEK
tallistr sourcing kpis --base-currency EUR --classification-mode ghgReceipt --search "travel"

`tallistr sourcing categories`

Use this when you want to know which categories dominate spend.

tallistr sourcing categories --base-currency SEK
tallistr sourcing categories --base-currency SEK --min-spend 1000 --search "software"

`tallistr sourcing category-suppliers`

Use this when you already know the category and want to know which suppliers dominate inside it.

tallistr sourcing category-suppliers --base-currency SEK --classification "travel"
tallistr sourcing category-suppliers --base-currency SEK --classification "it" --sub-classification "software"

`tallistr sourcing suppliers`

Use this when you want to know which suppliers account for the most spend.

tallistr sourcing suppliers --base-currency SEK
tallistr sourcing suppliers --base-currency EUR --min-spend 5000
tallistr sourcing suppliers --base-currency SEK --search "kantar" --format json

The --search option is useful for checking whether a tenant has purchased from a specific vendor or a list of target companies. Search can match supplier names and other receipt text, so filter or review the returned supplier names when the query is short or generic.

`tallistr sourcing supplier-categories`

Use this when you want to understand which categories make up a supplier's spend profile.

tallistr sourcing supplier-categories --base-currency SEK --canonical-supplier-id <supplierId>

`tallistr co2e-sourcing kpis`

Use this when the question is emissions-oriented, for example “what does our sourcing footprint look like?”.

tallistr co2e-sourcing kpis
tallistr co2e-sourcing kpis --scope 3 --sub-scope 6,7

`tallistr co2e-sourcing scope-breakdown`

Use this when you want to walk the emissions hierarchy from scope down to category or sub-category.

tallistr co2e-sourcing scope-breakdown
tallistr co2e-sourcing scope-breakdown --level sub-scope --scope 3
tallistr co2e-sourcing scope-breakdown --level category --scope 3 --sub-scope 6

`tallistr co2e-sourcing categories`

Use this when you want to know which categories contribute the most CO2e.

tallistr co2e-sourcing categories --scope 3
tallistr co2e-sourcing categories --scope 3 --min-co2e 100

`tallistr co2e-sourcing suppliers`

Use this when you want to know which suppliers contribute the most CO2e.

tallistr co2e-sourcing suppliers --scope 3

`tallistr co2e-sourcing drilldown`

Use this when you need the detailed records behind a sourcing footprint.

tallistr co2e-sourcing drilldown --scope 3 --sub-scope 6
tallistr co2e-sourcing drilldown --canonical-supplier-id <supplierId>

`tallistr receipts list`

Use this when you know the filters you want and need a paginated receipt list.

tallistr receipts list --limit 100 --offset 0
tallistr receipts list --classification travel --sort-by issueDate --sort-direction DESC

`tallistr receipts search`

Use this when the question starts with free text, such as a supplier, city, route, invoice number, or reference.

tallistr receipts search --query "hotel stockholm"
tallistr receipts search --query "uber" --search-target supplier --classification travel

`tallistr receipts get <receiptId>`

Fetch a receipt by ID.

tallistr receipts get 12345678-1234-1234-1234-123456789012 --format json

`tallistr reports summary`

Use this when you want a quick answer about report volume or coverage.

tallistr reports summary
tallistr reports summary --from-date 2025-01-01 --to-date 2025-12-31

`tallistr reports list`

Use this when you need to browse matching reports by date, search term, or sort order.

tallistr reports list
tallistr reports list --search "electricity" --sort-by createdAt --sort-direction desc

`tallistr reports get <reportId>`

Fetch a report by ID.

tallistr reports get 12345678-1234-1234-1234-123456789012 --format json

`tallistr vouchers list`

Use this when you want to inspect the accounting vouchers available for the current tenant or company.

tallistr vouchers list
tallistr vouchers list --limit 100 --offset 100

`tallistr vouchers get <voucherId>`

Fetch a voucher by ID.

tallistr vouchers get 12345678-1234-1234-1234-123456789012 --format json

`tallistr doctor`

Health check for API connectivity, authentication, and configuration.

$ tallistr doctor
Check               Status
─────────────────── ──────
API Connectivity    pass
Authentication      pass
Config Loaded       pass

# Machine-readable output
$ tallistr doctor --json

`tallistr mcp config`

Print connection and OAuth setup instructions for the hosted Tallistr HTTP MCP server.

tallistr mcp config
tallistr mcp config --client codex
tallistr mcp config --client claude
tallistr mcp config --client chatgpt

`tallistr mcp serve` (deprecated)

Local STDIO and ad-hoc HTTP serving no longer start a server. The command exits with migration instructions for https://mcp.tallistr.com/mcp.

Global Options

Every command accepts these flags:

| Flag | Description | Default | | --------------------- | ------------------------------------------------------------------------ | -------------- | | --format <fmt> | Output format for humans or automation: table, json, ndjson, csv | table/json | | --tenant <id> | Override tenant/workspace UUID (group of companies) | config default | | --legal-entity <id> | Filter to one company UUID inside the tenant | all entities | | --no-color | Disable ANSI colors | false | | --verbose | Debug logging to stderr | false | | -v, --version | Print version and exit | | | --help | Show help for any command | |

The default output format is table when stdout is a TTY, json when piped.

Configuration

The CLI stores its configuration in ~/.config/tallistr/config.json (or $XDG_CONFIG_HOME/tallistr/).

Configuration Precedence

Values are resolved in this order (first wins):

Command-line flags (--tenant, --format, etc.)
Environment variables (TALLISTR_TENANT_ID, TALLISTR_FORMAT)
Config file defaults (set via tenant use, legal-entity use)
Built-in defaults

Debug output follows the same leading precedence: --verbose wins over TALLISTR_DEBUG, then the built-in default is off. Debug mode is not persisted in the config file.

Output Formats

| Format | Use Case | Example | | -------- | --------------------------------------- | ------------------------------------------ | | table | Human-readable (default in TTY) | Column-aligned, ANSI colored | | json | Single JSON object (default when piped) | { "items": [...], "total": 42 } | | ndjson | Streaming, one JSON record per line | {"id":"...","co2eKg":1.23}\n | | csv | Spreadsheet import, data pipelines | "id","name","co2eKg"\n"...","...",1.23\n |

# Pipe to jq for field extraction
tallistr emissions summary --format json | jq '.totalCo2eKg'

# Count emission line items
tallistr emissions drilldown --format ndjson | wc -l

# Export suppliers to spreadsheet
tallistr supplier list --format csv > suppliers.csv

MCP Integration

Tallistr supports MCP through its hosted, read-only Streamable HTTP server:

https://mcp.tallistr.com/mcp

MCP clients authenticate directly through the hosted OAuth flow. Tallistr CLI tokens cannot be reused as hosted MCP credentials.

Codex

codex mcp add tallistr --url https://mcp.tallistr.com/mcp
codex mcp login tallistr

Claude

Configure https://mcp.tallistr.com/mcp as a remote connector in Claude settings, or use Claude Code:

claude mcp add --transport http tallistr https://mcp.tallistr.com/mcp

Claude Code also discovers the repository's .mcp.json automatically.

GitHub Copilot

Copilot CLI discovers .mcp.json, and VS Code Copilot discovers .vscode/mcp.json. Both authenticate to the hosted Tallistr MCP interactively. GitHub's cloud agent does not currently support OAuth for remote MCP servers, so its repository-settings template includes only the network-allowlisted, rate-limited, read-only Storybook MCP endpoint.

ChatGPT

Add https://mcp.tallistr.com/mcp as a remote MCP app in ChatGPT developer mode. The network-allowlisted Storybook server can separately be registered as https://storybook.tallistr.com/mcp.

Available MCP Tools

The question-first catalogue resolves the company, reporting period, currency, and internal Tallistr identifiers for the caller:

| Tool | Best for answering | | ------------------------- | --------------------------------------------------------------------------------- | | check_connection | “Can Tallistr access my connected company data?” | | describe_available_data | “Which companies, periods, currencies, and sources are available?” | | analyze_suppliers | “Who are our largest suppliers by spend or CO2e?” | | analyze_purchases | “What did we purchase and which categories dominate?” | | analyze_emissions | “What drives emissions by scope, supplier, category, or method?” | | compare_performance | “How did spend or emissions change, and which drivers explain it?” | | find_evidence | “Find the receipt, voucher, report, property, or declaration behind this result.” | | explain_calculation | “How was this result or evidence record calculated?” | | assess_data_quality | “Which data is missing, uncertain, or unconverted?” | | find_policy_findings | “Which source documents contain reported compliance findings?” |

The hosted deployment may temporarily expose the legacy tools alongside these tools during migration. See docs/mcp/normal-analysis-workflow.md for scope resolution and catalogue-profile behavior.

Available MCP Resources

| URI | Best for reading | | --------------------------------------------------- | --------------------------------------------------------- | | tallistr://tenants | Available tenants/workspaces or company groups | | tallistr://tenants/{tenantId}/legal-entities | Companies inside a tenant | | tallistr://tenants/{tenantId}/emissions/summary | Current year-to-date emissions snapshot | | tallistr://tenants/{tenantId}/sourcing/categories | Spend-based category analytics | | tallistr://tenants/{tenantId}/sourcing/suppliers | Spend-based supplier analytics | | tallistr://tenants/{tenantId}/receipts/search | Search-driven receipt result sets | | tallistr://tenants/{tenantId}/vouchers | Voucher lists for a tenant or filtered company | | tallistr://taxonomy/emission-categories | Reference taxonomy for emission categories | | tallistr://taxonomy/scopes | Reference taxonomy for GHG Protocol scopes and sub-scopes |

Environment Variables

| Variable | Description | | -------------------------- | ---------------------------------------------------------------------------------------------------------- | | TALLISTR_API_URL | Trusted Tallistr API origin (default: https://api.tallistr.com; production, staging, local, or loopback) | | TALLISTR_TOKEN | Bearer token for CI/headless auth (skips OAuth) | | TALLISTR_TENANT_ID | Default tenant ID | | TALLISTR_LEGAL_ENTITY_ID | Default legal entity ID | | TALLISTR_FORMAT | Default output format | | TALLISTR_CLIENT_ID | Optional override for OAuth client ID (default: 8788321e-17d0-4057-a30c-9db4740bb92b) | | TALLISTR_ISSUER_URL | Explicit OAuth issuer override; otherwise use API capability discovery (no fallback on discovery failure). | | TALLISTR_CONFIG_DIR | Override config directory (default: XDG) | | TALLISTR_DEBUG | Enable debug logging and detailed stack traces (1, true, or yes) | | NO_COLOR | Disable color output (per https://no-color.org) |

Exit Codes

| Code | Meaning | | ---- | ----------------------- | | 0 | Success | | 1 | General / unknown error | | 2 | Authentication failure | | 3 | Authorization failure | | 4 | Not found | | 5 | Validation error |

Error Verbosity

Default mode (production-friendly): concise one-line tagged errors, for example AuthenticationError: Authentication required.
Debug mode: full stack traces and detailed error objects.

Enable debug mode with either:

tallistr --verbose emissions summary
# or
TALLISTR_DEBUG=1 tallistr emissions summary

Scripting Examples

# Export all emissions as CSV
tallistr emissions drilldown --format csv --limit 100000 > emissions.csv

# Check if authenticated (exit code 0 = yes)
tallistr auth status --format json | jq -e '.authenticated' > /dev/null

# CI pipeline: summarize emissions and fail if over threshold
TOTAL=$(tallistr emissions summary --format json | jq '.totalCo2eKg')
if (( $(echo "$TOTAL > 1000" | bc -l) )); then
  echo "CO2e threshold exceeded: ${TOTAL}kg"
  exit 1
fi

# List all suppliers sorted by name
tallistr supplier list --format json | jq '.items | sort_by(.canonicalSupplierDisplayName)'

# Check whether a tenant has spend with a list of target suppliers
tallistr tenant use "Tallistr Group"
tallistr legal-entity use all

companies=("kantar" "valu8" "apollo.io" "norstat" "surveymonkey" "tally" "wgsn")

for company in "${companies[@]}"; do
  tallistr sourcing suppliers \
    --base-currency SEK \
    --format json \
    --search "$company" \
    | jq -r --arg company "$company" '
      def norm:
        ascii_downcase
        | gsub("[^a-z0-9]+"; " ")
        | gsub("^ +| +$"; "");

      .suppliers
      | map(select((.name | norm) | contains($company | norm)))
      | if length == 0 then
          [$company, "No", "0", ""]
        else
          [
            $company,
            "Yes",
            (map(.totalSpend) | add | tostring),
            (map(.name) | join("; "))
          ]
        end
      | @tsv'
done

# Explain every receipt from a drilldown
tallistr emissions drilldown --format ndjson \
  | jq -r '.receiptId // empty' \
  | while read -r id; do tallistr explain "$id" --format json; done

Related Packages

@tallistr/mcp — Deprecated compatibility shim that points existing installations to the hosted HTTP MCP server.

Development

The published build output is obfuscated (minified with variable mangling) via minify: true in tsup.config.ts. Do not disable this unless explicitly required.

# From monorepo root
cd apps/cli

# Type check
pnpm typecheck

# Build for npm
pnpm build

# Run locally (development mode)
pnpm dev -- auth status
pnpm cli auth login
pnpm cli emissions summary

Requirements

Node.js >= 22
macOS, Windows, or Linux

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@tallistr/cli

Organizational Model

Installation

Quick Start

Authentication

Browser Flow (PKCE) — Recommended

Device Authorization Flow — Headless

Token Override — CI/CD

Managing Auth State

Rate Limits

Commands

tallistr tenant list

tallistr tenant use <id-or-name>

tallistr legal-entity list

tallistr legal-entity use <id>

tallistr emissions summary

tallistr emissions drilldown

tallistr explain <id>

tallistr supplier list

tallistr supplier search <query>

tallistr sourcing kpis

tallistr sourcing categories

tallistr sourcing category-suppliers

tallistr sourcing suppliers

tallistr sourcing supplier-categories

tallistr co2e-sourcing kpis

tallistr co2e-sourcing scope-breakdown

tallistr co2e-sourcing categories

tallistr co2e-sourcing suppliers

tallistr co2e-sourcing drilldown

tallistr receipts list

tallistr receipts search

tallistr receipts get <receiptId>

tallistr reports summary

tallistr reports list

tallistr reports get <reportId>

tallistr vouchers list

tallistr vouchers get <voucherId>

tallistr doctor

tallistr mcp config

tallistr mcp serve (deprecated)

Global Options

Configuration

Configuration Precedence

Output Formats

MCP Integration

Codex

Claude

GitHub Copilot

ChatGPT

Available MCP Tools

Available MCP Resources

Environment Variables

Exit Codes

Error Verbosity

Scripting Examples

Related Packages

Development

Requirements

`tallistr tenant list`

`tallistr tenant use <id-or-name>`

`tallistr legal-entity list`

`tallistr legal-entity use <id>`

`tallistr emissions summary`

`tallistr emissions drilldown`

`tallistr explain <id>`

`tallistr supplier list`

`tallistr supplier search <query>`

`tallistr sourcing kpis`

`tallistr sourcing categories`

`tallistr sourcing category-suppliers`

`tallistr sourcing suppliers`

`tallistr sourcing supplier-categories`

`tallistr co2e-sourcing kpis`

`tallistr co2e-sourcing scope-breakdown`

`tallistr co2e-sourcing categories`

`tallistr co2e-sourcing suppliers`

`tallistr co2e-sourcing drilldown`

`tallistr receipts list`

`tallistr receipts search`

`tallistr receipts get <receiptId>`

`tallistr reports summary`

`tallistr reports list`

`tallistr reports get <reportId>`

`tallistr vouchers list`

`tallistr vouchers get <voucherId>`

`tallistr doctor`

`tallistr mcp config`

`tallistr mcp serve` (deprecated)