@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:

1. Choose a tenant when you want to ask questions at group/workspace level.
2. 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.

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>

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

# 4. Verify everything works
tallistr doctor

Authentication

The CLI supports three authentication methods.

Browser Flow (PKCE) — Recommended

Opens your default browser to sign in via FusionAuth. Secure, human-friendly, and no need to copy 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.

$ tallistr auth login
Starting Device Authorization flow...

  User code:        ABCD-1234
  Verification URL: https://iam.tallistr.com/oauth2/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

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>

Set the default tenant for all subsequent commands.

$ tallistr tenant use 00000000-0000-0000-0000-000000000001
Default tenant set to 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

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 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 serve

Start the MCP server for AI agent integration. For a standalone MCP binary, see @tallistr/mcp.

# STDIO (default — Claude Desktop, VS Code, Cursor)
tallistr mcp serve

# HTTP transport on localhost
tallistr mcp serve --transport http --port 3100

# Remote HTTP (requires API key for non-loopback connections)
tallistr mcp serve --transport http --host 0.0.0.0 --api-key <key>

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 | | --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):

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

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

The CLI includes a built-in MCP (Model Context Protocol) server for LLM agent integration. For a standalone MCP binary, see @tallistr/mcp.

This is useful when you want an LLM to ask Tallistr the same kinds of questions a human would ask in the CLI, but through structured tools and resources instead of shell commands.

If you run the standalone MCP package, you can authenticate directly there (same OAuth2 flows):

tallistr-mcp auth login           # Device flow
tallistr-mcp auth login --browser # PKCE browser flow

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "tallistr": {
      "command": "tallistr",
      "args": ["mcp", "serve"],
      "env": {
        "TALLISTR_TOKEN": "<your-api-token>",
        "TALLISTR_API_URL": "https://api.tallistr.com"
      }
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json:

{
  "servers": {
    "tallistr": {
      "type": "stdio",
      "command": "tallistr",
      "args": ["mcp", "serve"]
    }
  }
}

Available MCP Tools

| Tool | Best for answering | | ------------------------------ | ------------------------------------------------------------------ | | list_tenants | “Which Tallistr workspaces or company groups can I access?” | | list_legal_entities | “Which companies exist inside this tenant?” | | query_emissions | “How much did this tenant or company emit in this period?” | | get_emission_drilldown | “Which detailed records drove these emissions?” | | explain_receipt | “Why was this receipt calculated this way?” | | explain_voucher | “Why was this voucher calculated this way?” | | list_suppliers | “Which canonical suppliers does Tallistr know for this tenant?” | | check_health | “Is the Tallistr integration ready for use?” | | get_sourcing_kpis | “What does our spend profile look like overall?” | | get_sourcing_categories | “Which spend categories are largest?” | | get_category_suppliers | “Which suppliers dominate this spend category?” | | get_sourcing_suppliers | “Which suppliers account for the most spend?” | | get_supplier_categories | “What categories make up this supplier's spend?” | | get_co2e_sourcing_kpis | “What does our sourcing footprint look like overall?” | | get_co2e_scope_breakdown | “How is CO2e distributed across scopes and categories?” | | get_co2e_sourcing_categories | “Which categories contribute the most CO2e?” | | get_co2e_sourcing_suppliers | “Which suppliers contribute the most CO2e?” | | get_co2e_sourcing_drilldown | “Which detailed records sit behind this sourcing footprint?” | | list_receipts | “Which receipts match these structured filters?” | | search_receipts | “Which receipts mention this text, supplier, route, or reference?” | | get_receipt | “Show me this specific receipt.” | | get_report_summary | “How many reports do we have and what do they cover?” | | list_reports | “Which reports match these dates or search terms?” | | get_report | “Show me this specific report.” | | list_vouchers | “Which vouchers are available for this tenant or company?” | | get_voucher | “Show me this specific voucher.” |

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 | Backend API base URL (default: https://api.tallistr.com) | | 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 | OAuth issuer URL (default: https://iam.tallistr.com) | | TALLISTR_CONFIG_DIR | Override config directory (default: XDG) | | TALLISTR_DEBUG | Enable debug logging and detailed stack traces (1 or true) | | 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)'

# 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 — Standalone MCP server binary for AI agent integration (same tools, no CLI commands).

Development

# 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