> ## 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.

# Organizations

> List, search, and manage organization context in the CLI

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

## Overview

Most CLI commands operate within an organization context. You must set an active organization before working with facilities, vehicles, emissions data, etc.

***

## List Organizations

View all organizations you have access to:

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

# Short alias
dcy org ls
```

Output:

```
Showing 3 organization(s)
ff4adcc7-... | Acme Corp      | is_child=No [current]
a1b2c3d4-... | Acme Logistics | is_child=Yes
b2c3d4e5-... | Acme UK        | is_child=Yes
```

The `[current]` marker indicates your active organization.

| Flag               | Default | Description                             |
| ------------------ | ------- | --------------------------------------- |
| `--sort-by`        | —       | Sort field (only `name` supported)      |
| `--sort-order`     | `asc`   | Sort order: `asc` or `desc`             |
| `--show-hierarchy` | `false` | Show child counts and organization type |

### Hierarchy View

Use `--show-hierarchy` to see the role of each organization in the group:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy org list --show-hierarchy
```

Output:

```
Showing 3 organization(s)
ff4adcc7-... | Acme Holding  | type=parent       | children=2 [current]
a1b2c3d4-... | Acme Spain    | type=child         | children=0
b2c3d4e5-... | Acme UK       | type=intermediate  | children=1
```

Organization types: `parent` (has children, no parent), `child` (has parent, no children), `intermediate` (has both), `standalone` (neither).

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Sort by name descending
dcy org list --sort-by name --sort-order desc

# JSON for scripting
dcy org list --format json | jq '.[] | {id, company_name}'
```

***

## Set Active Organization

Switch your working context to a specific organization:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy org set ff4adcc7-8172-45fe-9cf1-e90a6de53aa9
```

Output:

```
organization set to Acme Corp
organization_id: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9
```

If the organization is not found, the CLI suggests alternatives:

```
organization ff4adcc7-... not found in your memberships
- Acme Corp (ff4adcc7-...)
- Acme Logistics (a1b2c3d4-...)
... and 3 more
```

<Tip>
  The active organization is stored in your config file (`~/.config/dcycle/v2/config.yaml`) and persists across sessions.
</Tip>

***

## Show Organization Details

View detailed information about a specific organization:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy org show ff4adcc7-8172-45fe-9cf1-e90a6de53aa9
```

Output:

```
ID: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9
Name: Acme Corp
Country: ES
Sector: manufacture
VAT: B12345678
Employees: 250
Status: active
Subscription: enterprise
API Enabled: true
Enabled: true
Is Dummy: false
Created: 2023-01-15
Is Child Org: No
Child Organizations: 2
  - Acme Spain (a1b2c3d4-...)
  - Acme UK (b2c3d4e5-...)
```

Without an argument, shows the active organization:

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

***

## Organization Tree

For holdings with subsidiaries, view the organizational hierarchy:

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

Output:

```
Acme Holding Corp (ff4adcc7-...)
├── Acme Spain (a1b2c3d4-...)
│   ├── Acme Madrid Office (c3d4e5f6-...)
│   └── Acme Barcelona Warehouse (d4e5f6g7-...)
├── Acme UK (b2c3d4e5-...)
│   └── Acme London Office (e5f6g7h8-...)
└── Acme Logistics (f6g7h8i9-...)
```

| Flag          | Default | Description                                                      |
| ------------- | ------- | ---------------------------------------------------------------- |
| `--from-root` | `false` | Start tree from root parent (useful when you're in a subsidiary) |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# View tree from root when logged into a subsidiary
dcy org tree --from-root

# View tree for a specific organization
dcy org tree a1b2c3d4-5678-90ab-cdef-1234567890ab

# JSON output for programmatic processing
dcy org tree --format json
```

***

## Create Organization

Create a new organization:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy org create \
  --name "Subsidiary SL" \
  --country ES \
  --sector manufacture \
  --employees 50 \
  --vat B12345678
```

| Flag          | Required | Description                              |
| ------------- | -------- | ---------------------------------------- |
| `--name`      | Yes      | Company name                             |
| `--country`   | Yes      | ISO country code (e.g. `ES`, `DE`, `UK`) |
| `--sector`    | Yes      | Business sector (see table below)        |
| `--employees` | Yes      | Employee count (must be > 0)             |
| `--vat`       | No       | VAT number                               |
| `--is-group`  | No       | Create as group/holding organization     |
| `--user-id`   | No       | User ID to assign as admin               |

### Valid Sectors

| Sector                       | Description                     |
| ---------------------------- | ------------------------------- |
| `agriculture`                | Agriculture                     |
| `extractive`                 | Extractive industries           |
| `manufacture`                | General manufacturing           |
| `manufacture_cleaning`       | Cleaning products manufacturing |
| `manufacture_cosmetics`      | Cosmetics manufacturing         |
| `manufacture_food`           | Food manufacturing              |
| `manufacture_furniture`      | Furniture manufacturing         |
| `manufacture_textile`        | Textile manufacturing           |
| `electricity_gas_supply`     | Electricity & gas supply        |
| `water_waste_supply`         | Water & waste supply            |
| `construction`               | Construction                    |
| `arquitecture`               | Architecture                    |
| `wholesale`                  | Wholesale                       |
| `trade_cleaning`             | Cleaning products trade         |
| `trade_cosmetics`            | Cosmetics trade                 |
| `trade_food`                 | Food trade                      |
| `trade_furniture`            | Furniture trade                 |
| `trade_textile`              | Textile trade                   |
| `textile_trade`              | Textile trade (alias)           |
| `transport`                  | Transport & logistics           |
| `hostelry`                   | Hotels & restaurants            |
| `information_communications` | IT & communications             |
| `finance`                    | Financial services              |
| `real_estate`                | Real estate                     |
| `scientific`                 | Science & technology            |
| `marketing`                  | Marketing & advertising         |
| `administrative`             | Administrative services         |
| `public_administration`      | Public administration           |
| `education`                  | Education                       |
| `sanitary`                   | Healthcare                      |
| `artistic`                   | Arts & entertainment            |
| `domestic`                   | Domestic services               |
| `extraterritorial`           | Extraterritorial organizations  |
| `other`                      | Other                           |

***

## Edit Organization

Update organization details:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy org edit <org-id> --name "New Name" --country ES --sector manufacture
```

Without an org-id argument, edits the active organization.

| Flag               | Short | Description                                 |
| ------------------ | ----- | ------------------------------------------- |
| `--name`           | `-n`  | New organization name                       |
| `--country`        | `-c`  | Country code                                |
| `--sector`         | `-s`  | Business sector (see table above)           |
| `--employees`      | `-e`  | Employee count                              |
| `--status`         | —     | `active` or `inactive`                      |
| `--api-enabled`    | —     | Enable API access                           |
| `--no-api-enabled` | —     | Disable API access                          |
| `--enabled`        | —     | Organization enabled: `true` or `false`     |
| `--is-dummy`       | —     | Mark as dummy/seeded data (superadmin only) |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Update employee count
dcy org edit -e 300

# Enable API access
dcy org edit --api-enabled

# Edit a different org without switching context
dcy org edit a1b2c3d4-... --name "Acme Spain Updated"
```

***

## Invite User

Invite a user to the active organization:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy org invite user@example.com --role member --lang es
```

| Flag           | Short | Default  | Description                        |
| -------------- | ----- | -------- | ---------------------------------- |
| `--role`       | `-r`  | `member` | Role: `admin`, `member`, or `fund` |
| `--send-email` | —     | `true`   | Send invitation email              |
| `--lang`       | —     | `en`     | Email language                     |
| `--org`        | —     | —        | Organization ID override           |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Invite as admin without email
dcy org invite admin@company.com --role admin --send-email=false

# Invite to a different organization
dcy org invite user@company.com --org a1b2c3d4-...
```

<Tip>
  `dcy org invite` is the same as `dcy member invite` — both use the same invitation flow.
</Tip>

***

## Bulk Create Child Organizations

Create multiple child organizations from a CSV file:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Preview without creating
dcy org bulk-create-children children.csv --dry-run

# Create organizations
dcy org bulk-create-children children.csv --yes
```

| Flag        | Short | Default | Description                          |
| ----------- | ----- | ------- | ------------------------------------ |
| `--dry-run` | —     | `false` | Preview without creating             |
| `--sector`  | `-s`  | `other` | Default sector for new organizations |
| `--yes`     | `-y`  | `false` | Skip confirmation prompt             |

### CSV Format

The CSV must have these columns:

| Column              | Required | Description                               |
| ------------------- | -------- | ----------------------------------------- |
| `organization_id`   | Yes      | Parent organization ID                    |
| `company_name`      | Yes      | New child company name                    |
| `vat_number`        | Yes      | VAT number                                |
| `country`           | Yes      | ISO country code                          |
| `employee_count`    | Yes      | Employee count                            |
| `share`             | Yes      | Ownership share (0-1 or percentage)       |
| `investment_scopes` | No       | Comma-separated scopes (default: `1,2,3`) |

```csv title="children.csv" theme={"theme":{"light":"github-light","dark":"github-dark"}}
organization_id,company_name,vat_number,country,employee_count,share
ff4adcc7-...,Acme Spain SL,B87654321,ES,50,100
ff4adcc7-...,Acme UK Ltd,GB123456789,UK,30,75
```

<Warning>
  Share values above 1 are treated as percentages (e.g. `75` → `0.75`).
</Warning>

***

## Parent-Child Linking

Link existing organizations into a corporate hierarchy using a two-step workflow: request, then confirm.

### Request Parent Link

Send a link request from child organizations to a parent. This triggers email invitations to the parent organization's owners.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Link a single child
dcy org request-parent-link \
  --child a1b2c3d4-... \
  --parent-id ff4adcc7-...

# Link multiple children
dcy org request-parent-link \
  --child a1b2c3d4-... \
  --child b2c3d4e5-... \
  --parent-id ff4adcc7-...

# Link by parent VAT instead of ID
dcy org request-parent-link \
  --child a1b2c3d4-... \
  --parent-vat B12345678

# Load children from CSV file
dcy org request-parent-link \
  --children-file subsidiaries.csv \
  --parent-id ff4adcc7-...
```

| Flag              | Description                                              |
| ----------------- | -------------------------------------------------------- |
| `--child`         | Child organization ID (repeatable for multiple children) |
| `--children-file` | CSV file with `child_org_id` column                      |
| `--parent-id`     | Parent organization ID                                   |
| `--parent-vat`    | Parent organization VAT (alternative to `--parent-id`)   |
| `--dry-run`       | Preview without sending requests                         |
| `--yes`, `-y`     | Skip confirmation prompt                                 |

### Confirm Parent Link

Accept or reject pending link requests (run from the parent organization):

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Accept a link
dcy org confirm-parent-link \
  --child a1b2c3d4-... \
  --parent-id ff4adcc7-... \
  --answer accepted \
  --share 75 \
  --investment-scopes 1,2,3

# Reject a link
dcy org confirm-parent-link \
  --child b2c3d4e5-... \
  --parent-id ff4adcc7-... \
  --answer rejected
```

| Flag                  | Default    | Description                                         |
| --------------------- | ---------- | --------------------------------------------------- |
| `--child`             | —          | Child organization ID (repeatable)                  |
| `--children-file`     | —          | CSV file with `child_org_id` column                 |
| `--parent-id`         | —          | Parent organization ID (required)                   |
| `--answer`            | `accepted` | Response: `accepted` or `rejected`                  |
| `--share`             | `1`        | Ownership share (values > 1 treated as percentages) |
| `--investment-scopes` | `1,2,3`    | Comma-separated investment scopes                   |
| `--tag`               | —          | Optional matrix tag                                 |
| `--dry-run`           | `false`    | Preview without confirming                          |
| `--yes`, `-y`         | `false`    | Skip confirmation prompt                            |

***

## Typical Workflows

### Quick Organization Switch for Scripts

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Save current context
ORIGINAL_ORG=$(dcy auth status --format json | jq -r '.organization_id')

# Work with another organization
dcy org set a1b2c3d4-5678-90ab-cdef-1234567890ab
dcy vehicle list --format json > logistics_vehicles.json

# Restore original context
dcy org set "$ORIGINAL_ORG"
```

### Build a Corporate Group

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 1. Create parent holding
dcy org create \
  --name "Acme Holding" \
  --country ES \
  --sector manufacture \
  --employees 500 \
  --is-group

# 2. Bulk create subsidiaries from CSV
dcy org bulk-create-children subsidiaries.csv --sector manufacture --yes

# 3. Verify the hierarchy
dcy org tree
```

### Link Existing Organizations

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 1. From the child org, request a link
dcy org set a1b2c3d4-...  # switch to child
dcy org request-parent-link \
  --child a1b2c3d4-... \
  --parent-id ff4adcc7-... \
  --dry-run  # preview first

dcy org request-parent-link \
  --child a1b2c3d4-... \
  --parent-id ff4adcc7-... \
  --yes

# 2. From the parent org, confirm the link
dcy org set ff4adcc7-...  # switch to parent
dcy org confirm-parent-link \
  --child a1b2c3d4-... \
  --parent-id ff4adcc7-... \
  --share 100 \
  --yes

# 3. Verify
dcy org tree
```

### Audit Group Structure

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Get all org IDs in the tree
dcy org tree --format json | jq -r '.. | .id? // empty' | sort -u

# Count children per organization
dcy org list --show-hierarchy --format json | \
  jq '.[] | select(.children_count > 0) | {name: .company_name, children: .children_count}'
```

***

## Current Context

Check your current organization context:

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

The output shows your active organization along with authentication details.

## Next Steps

<CardGroup cols={2}>
  <Card title="Members" icon="users" href="/cli/members">
    Manage organization members
  </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="Examples" icon="code" href="/cli/examples">
    Complete workflow examples
  </Card>

  <Card title="MCP Tools" icon="robot" href="/mcp/organizations">
    Query organization data from AI assistants via MCP
  </Card>
</CardGroup>