---
title: initiatives
description: Manage Initiative plans, Projects, and progress updates.
canonical_url: https://orchestor.io/docs/en/cli/initiative
markdown_url: https://orchestor.io/docs/en/cli/initiative.md
contentType: reference
---

# initiatives

`orc initiatives` creates Initiatives in a Workspace and updates their owner, priority, target date, and status. Add and reorder associated Projects, retrieve progress rollups, post comments and updates, and manage favorites and subscriptions. Deleted Initiatives can be restored.

Authentication and a selected Workspace are required. Updates must include `version` from the current response. Use a Project ID in the same Workspace when adding a Project.

## Usage

```bash title="terminal"
orc initiatives list --json
```

*List Initiatives in the Workspace.*

## Subcommands

### `list`

Lists Initiatives with tab or status filters, ordering, and pagination. An explicit `--status` overrides the tab when both are supplied.

```bash title="terminal"
orc initiatives list [options]
```

#### Unique options

##### `--tab`

Convenience filter: active selects active; planned selects proposed and planned. all or omission applies no tab filter. An explicit status takes precedence.; enum: active|planned|all

Type: `string`. Optional.

```bash title="terminal"
orc initiatives list --tab <value>
```

##### `--status`

Exact lifecycle-state filter. Overrides tab when both are supplied.

Type: `string`. Optional.

```bash title="terminal"
orc initiatives list --status <value>
```

##### `--sort`

Sort field. Defaults to created_at; manual uses the shared numeric rank and target_date uses the target calendar date.; enum: created_at|target_date|manual

Type: `string`. Optional.

```bash title="terminal"
orc initiatives list --sort <value>
```

##### `--order`

Sort direction. Defaults to descending for created_at and ascending for target_date or manual. Keep it unchanged while following a cursor.; enum: asc|desc

Type: `string`. Optional.

```bash title="terminal"
orc initiatives list --order <value>
```

### `create`

Creates an Initiative with a name. Names are trimmed and limited to 200 characters; blank names are rejected. You can also specify an owner, priority, target date, status, and labels.

```bash title="terminal"
orc initiatives create [options]
```

#### Unique options

##### `--idempotency-key`

Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation.

Type: `string`. Optional.

```bash title="terminal"
orc initiatives create --idempotency-key <value>
```

##### `--color`

Optional display color token. Null clears it; omission in an update preserves it.; (use "null" or "reset" to clear); max 100 chars

Type: `string`. Optional.

```bash title="terminal"
orc initiatives create --color <value>
```

##### `--description`

Description text. Use an empty string to clear it.; max 2000 chars

Type: `string`. Optional.

```bash title="terminal"
orc initiatives create --description <value>
```

##### `--icon`

Optional display icon token. Null clears it; omission in an update preserves it.; (use "null" or "reset" to clear); max 100 chars

Type: `string`. Optional.

```bash title="terminal"
orc initiatives create --icon <value>
```

##### `--labels`

Complete label set. Labels are trimmed and must be unique. Use [] to clear; omission in an update preserves the set.; csv

Type: `string`. Optional.

```bash title="terminal"
orc initiatives create --labels <value>
```

##### `--name`

(required) Initiative name. Leading and trailing whitespace is removed; a blank name is rejected.; max 200 chars

Type: `string`. Optional.

```bash title="terminal"
orc initiatives create --name <value>
```

##### `--owner-id`

Owner user ID belonging to this workspace. Null clears the owner; omission in an update preserves it.; (use "null" or "reset" to clear)

Type: `string`. Optional.

```bash title="terminal"
orc initiatives create --owner-id <value>
```

##### `--priority`

Priority label, or null when unset. Omission in an update preserves it.; enum: urgent|high|medium|low|; (use "null" or "reset" to clear)

Type: `string`. Optional.

```bash title="terminal"
orc initiatives create --priority <value>
```

##### `--status`

Body field: status

Type: `string`. Optional.

```bash title="terminal"
orc initiatives create --status <value>
```

##### `--target-date`

Target calendar date in YYYY-MM-DD form. Supply target_precision with it; set both to null to clear the target.; (use "null" or "reset" to clear)

Type: `string`. Optional.

```bash title="terminal"
orc initiatives create --target-date <value>
```

##### `--target-precision`

Target date granularity. Supply target_date together with this field; both must be non-null or both null.; enum: day|month|quarter|half_year|year|; (use "null" or "reset" to clear)

Type: `string`. Optional.

```bash title="terminal"
orc initiatives create --target-precision <value>
```

### `get`

Retrieves current information by Initiative ID. Read the update `version` from this response.

```bash title="terminal"
orc initiatives get <id> [options]
```

### `update`

Updates an Initiative using its ID and current `version`. A stale version causes a conflict. Omitted priority is preserved; `null` clears it. Use an empty string to clear the description.

```bash title="terminal"
orc initiatives update <id> [options]
```

#### Unique options

##### `--color`

Optional display color token. Null clears it; omission in an update preserves it.; (use "null" or "reset" to clear); max 100 chars

Type: `string`. Optional.

```bash title="terminal"
orc initiatives update <id> --color <value>
```

##### `--description`

Description text. Use an empty string to clear it.; max 2000 chars

Type: `string`. Optional.

```bash title="terminal"
orc initiatives update <id> --description <value>
```

##### `--icon`

Optional display icon token. Null clears it; omission in an update preserves it.; (use "null" or "reset" to clear); max 100 chars

Type: `string`. Optional.

```bash title="terminal"
orc initiatives update <id> --icon <value>
```

##### `--labels`

Complete label set. Labels are trimmed and must be unique. Use [] to clear; omission in an update preserves the set.; csv

Type: `string`. Optional.

```bash title="terminal"
orc initiatives update <id> --labels <value>
```

##### `--name`

Initiative name. Leading and trailing whitespace is removed; a blank name is rejected.; max 200 chars

Type: `string`. Optional.

```bash title="terminal"
orc initiatives update <id> --name <value>
```

##### `--owner-id`

Owner user ID belonging to this workspace. Null clears the owner; omission in an update preserves it.; (use "null" or "reset" to clear)

Type: `string`. Optional.

```bash title="terminal"
orc initiatives update <id> --owner-id <value>
```

##### `--priority`

Priority label, or null when unset. Omission in an update preserves it.; enum: urgent|high|medium|low|; (use "null" or "reset" to clear)

Type: `string`. Optional.

```bash title="terminal"
orc initiatives update <id> --priority <value>
```

##### `--rank`

Workspace-shared manual position as a non-negative decimal string. Lower values appear first for ascending manual order.; max 100 chars

Type: `string`. Optional.

```bash title="terminal"
orc initiatives update <id> --rank <value>
```

##### `--status`

Body field: status

Type: `string`. Optional.

```bash title="terminal"
orc initiatives update <id> --status <value>
```

##### `--target-date`

Target calendar date in YYYY-MM-DD form. Supply target_precision with it; set both to null to clear the target.; (use "null" or "reset" to clear)

Type: `string`. Optional.

```bash title="terminal"
orc initiatives update <id> --target-date <value>
```

##### `--target-precision`

Target date granularity. Supply target_date together with this field; both must be non-null or both null.; enum: day|month|quarter|half_year|year|; (use "null" or "reset" to clear)

Type: `string`. Optional.

```bash title="terminal"
orc initiatives update <id> --target-precision <value>
```

##### `--version`

(required) Latest saved version from the Initiative response. A stale value returns a conflict; read the current resource before retrying.

Type: `number`. Optional.

```bash title="terminal"
orc initiatives update <id> --version <value>
```

### `delete`

Soft-deletes an Initiative by ID.

```bash title="terminal"
orc initiatives delete <id> [options]
```

### `rollup get`

Retrieves an Initiative progress rollup, separate from retrieving individual settings.

```bash title="terminal"
orc initiatives rollup get <id> [options]
```

### `projects list`

Lists Projects associated with the Initiative. Paginate with `--limit` and `--cursor`.

```bash title="terminal"
orc initiatives projects list <id> [options]
```

### `projects create`

Adds a Project in the same Workspace using `project_id`. Membership `rank` is a non-negative integer; when omitted, the Project display order is used.

```bash title="terminal"
orc initiatives projects create <id> [options]
```

#### Unique options

##### `--project-id`

(required) ID of a project in the same workspace.

Type: `string`. Optional.

```bash title="terminal"
orc initiatives projects create <id> --project-id <value>
```

##### `--rank`

Non-negative integer membership rank. Defaults to the project display order when omitted.

Type: `number`. Optional.

```bash title="terminal"
orc initiatives projects create <id> --rank <value>
```

### `projects update`

Reorders an associated Project using the Initiative ID, Project ID, and a new `rank`. Lower non-negative integer values appear first.

```bash title="terminal"
orc initiatives projects update <id> <project-id> [options]
```

#### Unique options

##### `--rank`

(required) New non-negative integer membership rank. Lower values appear first.

Type: `number`. Optional.

```bash title="terminal"
orc initiatives projects update <id> <project-id> --rank <value>
```

### `projects delete`

Removes an association using the Initiative ID and Project ID. This is separate from archiving the Project itself.

```bash title="terminal"
orc initiatives projects delete <id> <project-id> [options]
```

### `activity list`

Lists Initiative activity.

```bash title="terminal"
orc initiatives activity list <id> [options]
```

### `comments list`

Lists Initiative comments.

```bash title="terminal"
orc initiatives comments list <id> [options]
```

### `comments create`

Posts a comment using an Initiative ID and `body`. Specify `parent_id` for a reply.

```bash title="terminal"
orc initiatives comments create <id> [options]
```

#### Unique options

##### `--body`

(required) Comment text. Trimmed before validation; must contain 1 to 10000 characters.; max 10000 chars

Type: `string`. Optional.

```bash title="terminal"
orc initiatives comments create <id> --body <value>
```

##### `--parent-id`

Top-level comment ID in this initiative. Omit or pass null to start a thread. Replies to replies are rejected.; (use "null" or "reset" to clear); max 500 chars

Type: `string`. Optional.

```bash title="terminal"
orc initiatives comments create <id> --parent-id <value>
```

### `favorites enable`

Adds the specified Initiative to favorites.

```bash title="terminal"
orc initiatives favorites enable <id> [options]
```

### `favorites disable`

Removes the specified Initiative from favorites.

```bash title="terminal"
orc initiatives favorites disable <id> [options]
```

### `restore`

Restores a soft-deleted Initiative by ID.

```bash title="terminal"
orc initiatives restore <id> [options]
```

### `subscriptions enable`

Subscribes to the specified Initiative.

```bash title="terminal"
orc initiatives subscriptions enable <id> [options]
```

### `subscriptions disable`

Unsubscribes from the specified Initiative.

```bash title="terminal"
orc initiatives subscriptions disable <id> [options]
```

### `updates list`

Lists Initiative progress updates.

```bash title="terminal"
orc initiatives updates list <id> [options]
```

### `updates create`

Posts an Initiative update using its ID, `body`, and `health`. This is separate from an ordinary comment.

```bash title="terminal"
orc initiatives updates create <id> [options]
```

#### Unique options

##### `--body`

(required) Progress-update text. Trimmed before validation; must contain 1 to 10000 characters.; max 10000 chars

Type: `string`. Optional.

```bash title="terminal"
orc initiatives updates create <id> --body <value>
```

##### `--health`

(required) Body field: health

Type: `string`. Optional.

```bash title="terminal"
orc initiatives updates create <id> --health <value>
```

### `batch update`

Executes multiple actions in JSON `items`. Items are processed independently in input order; result indices refer to the input array. Individual failures do not roll back successful items.

```bash title="terminal"
orc initiatives batch update [options]
```

#### Unique options

##### `--idempotency-key`

Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation.

Type: `string`. Optional.

```bash title="terminal"
orc initiatives batch update --idempotency-key <value>
```

##### `--items`

(required) Actions processed independently in input order. Each result index refers to this array. A malformed request is rejected before processing; reported item failures do not roll back successful items.; JSON array of objects (use --stdin for large resources)

Type: `string`. Optional.

```bash title="terminal"
orc initiatives batch update --items <value>
```

## Examples

### Create an Initiative with a name.

```bash title="terminal"
orc initiatives create --name "Improve onboarding" --json
```

*Create an Initiative with a name.*

### Read current information and submit an update file.

Include the retrieved `version` and fields to change in the JSON.

```bash title="terminal"
orc initiatives get INITIATIVE_ID --json
orc initiatives update INITIATIVE_ID --stdin < initiative-update.json --json
```

*Read current information and submit an update file.*

### Add a Project from the same Workspace.

```bash title="terminal"
orc initiatives projects create INITIATIVE_ID --project-id PROJECT_ID --json
```

*Add a Project from the same Workspace.*

### Reorder an associated Project.

```bash title="terminal"
orc initiatives projects update INITIATIVE_ID PROJECT_ID --rank 0 --json
```

*Reorder an associated Project.*

### Retrieve the Initiative progress rollup.

```bash title="terminal"
orc initiatives rollup get INITIATIVE_ID --json
```

*Retrieve the Initiative progress rollup.*

## Update conflicts and ordering

If an update conflicts, read the current content and `version` with `get`, review the changes, and resubmit. Check each batch item’s result. A malformed request is rejected before processing, but individual failures do not undo successful items.

An Initiative’s own manual `rank` is a non-negative decimal string. In contrast, the `rank` of a Project’s membership in an Initiative is a non-negative integer. These order different resources; do not confuse their value types.

## Global Options

The following [global options](https://orchestor.io/docs/cli/global-flags.md) can be used with `orc initiatives`:

- [`--help`](https://orchestor.io/docs/cli/global-flags.md#help)
- [`--workspace`](https://orchestor.io/docs/cli/global-flags.md#workspace)
- [`--json`](https://orchestor.io/docs/cli/global-flags.md#json-output)
- [`--pretty`](https://orchestor.io/docs/cli/global-flags.md#json-output)
- [`--format`](https://orchestor.io/docs/cli/global-flags.md#output-format)
- [`--field`](https://orchestor.io/docs/cli/global-flags.md#field-selection)
- [`--fields`](https://orchestor.io/docs/cli/global-flags.md#field-selection)
- [`--raw`](https://orchestor.io/docs/cli/global-flags.md#raw-output)
- [`--output`](https://orchestor.io/docs/cli/global-flags.md#file-output)
- [`--no-pager`](https://orchestor.io/docs/cli/global-flags.md#pager)
- [`--dry-run`](https://orchestor.io/docs/cli/global-flags.md#dry-run)
- [`--yes`](https://orchestor.io/docs/cli/global-flags.md#confirmation)
- [`--limit`](https://orchestor.io/docs/cli/global-flags.md)
- [`--cursor`](https://orchestor.io/docs/cli/global-flags.md)
- [`--stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input)
- [`--from-stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input)
- [`--page-all`](https://orchestor.io/docs/cli/global-flags.md#all-pages)
- [`--timing`](https://orchestor.io/docs/cli/global-flags.md#request-timing)
- [`--readonly`](https://orchestor.io/docs/cli/global-flags.md#read-only-mode)
- [`--wrap-untrusted`](https://orchestor.io/docs/cli/global-flags.md#untrusted-content-wrapping)

For details and examples, see [global options](https://orchestor.io/docs/cli/global-flags.md).

---

[Documentation index](https://orchestor.io/docs/llms.txt)