> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Overview

> Command-line interface for Dcycle operational data management

<Note>
  **Early Access** - The Dcycle CLI is currently available for enterprise customers.
  [Contact us](/docs/support) to learn more about access.
</Note>

## What is the Dcycle CLI?

The Dcycle CLI (`dcy`) is a command-line tool that allows you to interact with Dcycle's operational data platform directly from your terminal. It's designed for:

* **Bulk operations**: Upload large datasets via CSV files
* **Automation**: Integrate Dcycle into your CI/CD pipelines and scripts
* **Power users**: Quick access to data without navigating the web interface
* **Data management**: Export, filter, and manage your operational data programmatically

## Key Features

<CardGroup cols={2}>
  <Card title="Organization Management" icon="building">
    List, search, and switch between organizations. Manage members, invite users, and view hierarchy.
  </Card>

  <Card title="Facilities & Hubs" icon="warehouse">
    Manage facilities, logistic hubs, and bulk upload vehicles via CSV templates.
  </Card>

  <Card title="Emissions Data" icon="leaf">
    Work with employee commute, travel, invoices, purchases, shipments, and transport routes.
  </Card>

  <Card title="Logistics Integration" icon="truck">
    Upload transport requests, fuel recharges, and manage logistics hubs.
  </Card>

  <Card title="Projects & Tasks" icon="clipboard-list">
    Create sustainability projects (carbon footprint, LCA, ISO audits) and manage tasks.
  </Card>

  <Card title="Files & Readings" icon="file">
    Upload documents, view extracted readings, and create invoices from parsed files.
  </Card>

  <Card title="Widgets & Dashboards" icon="chart-pie">
    Build pivot tables, charts, and KPI widgets on project dashboards. Filter, add intensity measures, and export CSV.
  </Card>

  <Card title="Admin Operations" icon="shield-halved">
    Trigger backend recalculations (Scope 3 T\&D, waste transport) and insert energy records.
  </Card>
</CardGroup>

## Installation

Install with Homebrew (macOS and Linux):

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
brew tap Dcycle-by-WUM/tap https://github.com/Dcycle-by-WUM/homebrew-tap
brew install dcy
```

Verify the install:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy version
```

## Updating

To update to the latest version:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
brew update && brew upgrade dcy
```

## Quick Reference

### Authentication & Config

| Command                      | Description                                       |
| ---------------------------- | ------------------------------------------------- |
| `dcy auth login`             | Authenticate with Dcycle                          |
| `dcy auth logout`            | Log out                                           |
| `dcy auth status`            | View current session info                         |
| `dcy auth set-api-key <key>` | Store API key for non-interactive auth            |
| `dcy config list`            | Show current configuration                        |
| `dcy config host set <env>`  | Switch environment (production/staging/dev/local) |
| `dcy config reset`           | Reset configuration to defaults                   |
| `dcy version`                | Print CLI version                                 |
| `dcy version --check`        | Check for updates                                 |
| `dcy doctor`                 | Verify CLI setup and connectivity                 |
| `dcy completion <shell>`     | Generate shell completion script                  |

### Organization & Members

| Command                              | Description                         |
| ------------------------------------ | ----------------------------------- |
| `dcy org list`                       | List accessible organizations       |
| `dcy org set <id>`                   | Set active organization             |
| `dcy org show <id>`                  | Show organization details           |
| `dcy org tree`                       | Show organization hierarchy         |
| `dcy org create`                     | Create organization                 |
| `dcy org edit <id>`                  | Edit organization                   |
| `dcy org invite <email>`             | Invite user to organization         |
| `dcy org bulk-create-children <csv>` | Create child organizations from CSV |
| `dcy org request-parent-link`        | Request parent-child link           |
| `dcy org confirm-parent-link`        | Accept/reject parent link requests  |
| `dcy member list`                    | List organization members           |
| `dcy member invite <email>`          | Invite member                       |
| `dcy member edit <id>`               | Change member role                  |
| `dcy member delete <id>`             | Remove member                       |

### Assets

| Command                           | Description                      |
| --------------------------------- | -------------------------------- |
| `dcy facility list`               | List facilities                  |
| `dcy facility create`             | Create facility                  |
| `dcy facility edit <id>`          | Edit facility                    |
| `dcy facility delete <id>`        | Delete facility                  |
| `dcy vehicle list`                | List fleet vehicles              |
| `dcy vehicle create`              | Create vehicle                   |
| `dcy vehicle edit <id>`           | Edit vehicle                     |
| `dcy vehicle upload`              | Bulk upload vehicles from CSV    |
| `dcy vehicle diagnose <id>`       | Diagnose vehicle emission issues |
| `dcy vehicle recalculate <id>`    | Trigger emission recalculation   |
| `dcy vehicle delete-consumptions` | Bulk delete consumption records  |
| `dcy vehicle-fuel list`           | List available vehicle fuels     |
| `dcy vehicle-fuel list-types`     | List vehicle type categories     |
| `dcy hub list`                    | List logistic hubs               |
| `dcy hub create`                  | Create hub                       |
| `dcy hub edit <id>`               | Edit hub                         |
| `dcy hub delete <id>`             | Delete hub                       |

### Emissions Data

| Command                                  | Description                                |
| ---------------------------------------- | ------------------------------------------ |
| `dcy survey send <emails>`               | Send mobility surveys to employees         |
| `dcy survey resend <emails>`             | Resend surveys to pending employees        |
| `dcy survey list`                        | List survey employees and status           |
| `dcy employee list`                      | List employee commute records              |
| `dcy employee create employee`           | Create employee                            |
| `dcy employee create add-period <id>`    | Add commute period                         |
| `dcy employee create import-periods`     | Bulk import employees from CSV             |
| `dcy employee set update-historic <csv>` | Bulk update historic periods from CSV      |
| `dcy travel list`                        | List business travel records               |
| `dcy transport list`                     | List transport routes                      |
| `dcy invoice list`                       | List energy invoices                       |
| `dcy invoice edit <id> [<id>...]`        | Enable/disable/update invoice(s)           |
| `dcy invoice recalculate`                | Recalculate invoice emissions (one-by-one) |
| `dcy invoice recalculate-v2`             | Batch recalculate by activity category     |
| `dcy invoice recalculate-legacy`         | Batch recalculate via legacy endpoint      |
| `dcy purchase list`                      | List purchases                             |
| `dcy purchase upload`                    | Bulk upload purchases from CSV             |
| `dcy shipment list`                      | List shipments                             |
| `dcy shipment create`                    | Create shipment                            |

### Logistics

| Command                            | Description                                        |
| ---------------------------------- | -------------------------------------------------- |
| `dcy logistics requests list`      | List transport requests                            |
| `dcy logistics requests show <id>` | Show request details                               |
| `dcy logistics status`             | Show logistics summary (requests, recharges, hubs) |
| `dcy logistics upload`             | Upload CSV data (requests or recharges)            |
| `dcy logistics clients`            | List available clients                             |
| `dcy logistics tocs`               | List cargo types                                   |

### Files & Projects

| Command                                | Description                    |
| -------------------------------------- | ------------------------------ |
| `dcy file upload <path>`               | Upload a file                  |
| `dcy file list`                        | List uploaded files            |
| `dcy file reading list`                | List file readings             |
| `dcy file reading create-records <id>` | Create invoices from a reading |
| `dcy project list`                     | List projects                  |
| `dcy project create`                   | Create project                 |
| `dcy project task list <id>`           | List project tasks             |
| `dcy project task create <id>`         | Create project task            |

### Widgets

| Command                                       | Description                            |
| --------------------------------------------- | -------------------------------------- |
| `dcy widget list <project-id>`                | List dashboard widgets                 |
| `dcy widget create <project-id>`              | Create a widget                        |
| `dcy widget update <project-id> <widget-id>`  | Update a widget's config               |
| `dcy widget results <project-id> <widget-id>` | Compute results (JSON or CSV)          |
| `dcy widget catalog [category]`               | Show available dimensions and measures |
| `dcy widget filter add`                       | Add a hierarchy filter                 |
| `dcy widget intensity groups`                 | List intensity metric groups           |

### Data Imports

| Command                            | Description                                |
| ---------------------------------- | ------------------------------------------ |
| `dcy imports create`               | Upload a file and start an import session  |
| `dcy imports suggest-mapping <id>` | Get AI-assisted column mapping suggestions |
| `dcy imports confirm-mapping <id>` | Lock in the column mapping                 |
| `dcy imports validate <id>`        | Validate rows against template rules       |
| `dcy imports patch <id>`           | Fix row-level errors                       |
| `dcy imports submit <id>`          | Submit import for processing               |
| `dcy imports status <id>`          | Check import session status                |
| `dcy imports list`                 | List import sessions                       |
| `dcy imports template <id>`        | View template columns and rules            |

### Reference & Advanced

| Command                                  | Description                         |
| ---------------------------------------- | ----------------------------------- |
| `dcy supplier list`                      | List available suppliers            |
| `dcy units list`                         | List available units                |
| `dcy own-workforce list`                 | List own workforce records          |
| `dcy own-workforce delete-bulk`          | Bulk delete own workforce records   |
| `dcy sold-product delete-bulk`           | Bulk delete sold product records    |
| `dcy waste-water-treatments recalculate` | Recalculate WWT emissions           |
| `dcy custom-ef upload`                   | Upload custom emission factors      |
| `dcy custom-ef delete-bulk`              | Bulk delete custom emission groups  |
| `dcy lca link`                           | Link LCA materials to ecoinvent     |
| `dcy lca edit <id>`                      | Edit ecoinvent match for a material |

### Admin

| Command                                          | Description                                           |
| ------------------------------------------------ | ----------------------------------------------------- |
| `dcy admin recalculate-scope3-td <org-id>`       | Recalculate Scope 3 T\&D data                         |
| `dcy admin recalculate-waste-transport <org-id>` | Re-split waste emissions into management vs transport |
| `dcy admin energy`                               | Insert or update energy records directly (kWh)        |

## Global Flags

These flags are available on every command:

| Flag                    | Description                                |
| ----------------------- | ------------------------------------------ |
| `--format <text\|json>` | Output format (default: `text`)            |
| `--json`                | Shorthand for `--format json`              |
| `--verbose`, `-v`       | Show HTTP requests and responses on stderr |
| `--timeout <seconds>`   | HTTP request timeout (default: `30`)       |
| `--no-color`            | Disable ANSI color output                  |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# JSON output (shorthand)
dcy vehicle list --json

# Debug an API call
dcy vehicle list --verbose

# Increase timeout for slow connections
dcy facility list --timeout 60

# Combine flags
dcy purchase list --json --verbose --timeout 90
```

<Tip>
  Verbose output goes to stderr, so it won't interfere with JSON piped to other tools:
  `dcy vehicle list --json --verbose | jq '.'`
</Tip>

## Output Formats

The CLI supports multiple output formats:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Default: Rich table format (human-readable)
dcy vehicle list

# JSON format (for scripting)
dcy vehicle list --json

# Pipe to other tools
dcy vehicle list --json | jq '.[] | .plate'

# Disable colors (also respects NO_COLOR env var)
dcy vehicle list --no-color
```

Set a default format via environment variable:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export DCYCLE_FORMAT=json
dcy vehicle list  # outputs JSON without --format flag
```

## Environment Variables

All settings can be controlled via environment variables, useful for CI/CD pipelines and scripts:

| Variable         | Description                                          | Default |
| ---------------- | ---------------------------------------------------- | ------- |
| `DCYCLE_API_KEY` | API key for non-interactive auth (skips OAuth login) | —       |
| `DCYCLE_HOST`    | Override the API host URL                            | —       |
| `DCYCLE_ORG_ID`  | Override the active organization                     | —       |
| `DCYCLE_FORMAT`  | Default output format: `text` or `json`              | `text`  |
| `DCYCLE_VERBOSE` | Enable verbose HTTP logging (`1` or `true`)          | —       |
| `DCYCLE_TIMEOUT` | HTTP request timeout in seconds                      | `30`    |
| `NO_COLOR`       | Disable ANSI colors when set to any value            | —       |

Command-line flags always take precedence over environment variables.

## Shell Completions

Enable tab completion for commands, flags, and values:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Bash
source <(dcy completion bash)

# Zsh
source <(dcy completion zsh)

# Fish
dcy completion fish | source

# PowerShell
dcy completion powershell | Out-String | Invoke-Expression
```

To load completions permanently, see `dcy completion --help` for per-shell instructions.

<Tip>
  Shell completions include context-aware values — for example, `--status` suggests valid status values and `--format` suggests `text` or `json`.
</Tip>

## Aliases

Most `list` subcommands support `ls` as a short alias:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy facility ls       # same as dcy facility list
dcy vehicle ls        # same as dcy vehicle list
dcy purchase ls       # same as dcy purchase list
```

## Troubleshooting

Run `dcy doctor` to verify your CLI setup:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy doctor
```

This checks your config file, API host, authentication, organization, and CLI version. Use `--format json` for machine-readable output.

## Getting Help

Every command supports the `--help` flag:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy --help              # Show all commands
dcy org --help          # Show organization commands
dcy vehicle list --help # Show list options and filters
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/cli/authentication">
    Learn how to authenticate and configure the CLI
  </Card>

  <Card title="Organizations" icon="sitemap" href="/cli/organizations">
    Manage your organization context and members
  </Card>

  <Card title="Vehicles" icon="car" href="/cli/vehicles">
    Manage fleet vehicles, fuel types, and CSV uploads
  </Card>

  <Card title="Facilities" icon="warehouse" href="/cli/facilities">
    Manage physical locations and their emissions
  </Card>

  <Card title="Invoices" icon="file-invoice" href="/cli/invoices">
    Manage energy invoices for Scope 1 and Scope 2 emissions
  </Card>

  <Card title="Projects" icon="clipboard-list" href="/cli/projects">
    Create and manage sustainability projects
  </Card>

  <Card title="Data Imports" icon="upload" href="/cli/imports">
    Bulk import CSV/Excel with guided mapping and validation
  </Card>

  <Card title="Widgets" icon="chart-pie" href="/cli/widgets">
    Build dashboard widgets, charts, and export data
  </Card>

  <Card title="Admin" icon="shield-halved" href="/cli/admin">
    Recalculations and direct data manipulation
  </Card>

  <Card title="MCP Server" icon="robot" href="/mcp/overview">
    Query your data from AI assistants via MCP
  </Card>
</CardGroup>