---
title: projects
description: Manage Project plans, progress, and lifecycle.
canonical_url: https://orchestor.io/docs/en/cli/project
markdown_url: https://orchestor.io/docs/en/cli/project.md
contentType: reference
---

# projects

`orc projects` creates Projects in a Workspace, updates plans such as owners, dates, and priorities, and retrieves progress rollups. Archive unused Projects and restore them later.

Authentication and a selected Workspace are required. The `project_key` supplied on creation is a lookup key unique within the Workspace and cannot be changed through updates. Pass this key to `get`, `update`, `archive`, and `restore`.

## Usage

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

*List Projects in the Workspace.*

## Subcommands

### `list`

Lists Projects. Include archived Projects with `--include-archived`, and paginate with `--limit` and `--cursor`.

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

#### Unique options

##### `--workspace-id`

Workspace context. Organization-scoped credentials must supply a workspace in their organization. Workspace-scoped API keys remain bound to their authenticated workspace; this value cannot redirect them to another workspace.

Type: `string`. Optional.

```bash title="terminal"
orc projects list --workspace-id <value>
```

##### `--include-archived`

Include archived projects in the response.; enum: true|false

Type: `string`. Optional.

```bash title="terminal"
orc projects list --include-archived <value>
```

### `create`

Creates a Project using `project_key` and `name`. If status is omitted on creation, it defaults to `planned`. You can also specify an `initiative_id` in the same Workspace or milestone JSON.

```bash title="terminal"
orc projects 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 projects create --idempotency-key <value>
```

##### `--project-key`

(required) Project lookup key, unique within the workspace. Must not contain slash, backslash or two consecutive dots. This key cannot be changed through the update endpoint.

Type: `string`. Optional.

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

##### `--name`

(required) Display name.

Type: `string`. Optional.

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

##### `--status`

Project lifecycle status. Omitted on creation, it defaults to planned.; enum: planned|in_progress|paused|completed|canceled

Type: `string`. Optional.

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

##### `--priority`

Project priority; null means unassigned.; enum: urgent|high|medium|low; (use "null" or "reset" to clear)

Type: `string`. Optional.

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

##### `--lead-id`

Active workspace member id of the project lead. null means no lead is assigned.; (use "null" or "reset" to clear)

Type: `string`. Optional.

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

##### `--start-date`

Planned start as YYYY, YYYY-MM or YYYY-MM-DD. This is a calendar value, not a timestamp. null clears it.; (use "null" or "reset" to clear)

Type: `string`. Optional.

```bash title="terminal"
orc projects create --start-date <value>
```

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

Target completion as YYYY, YYYY-MM or YYYY-MM-DD. This is a calendar value, not a timestamp. null clears it.; (use "null" or "reset" to clear)

Type: `string`. Optional.

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

##### `--member-ids`

Active workspace member ids assigned to this project. The array replaces the current assignment on update; an empty array clears it. These assignments do not define the workspace access boundary.; csv

Type: `string`. Optional.

```bash title="terminal"
orc projects create --member-ids <value>
```

##### `--labels`

Project label values. The array replaces current labels on update; an empty array clears them. At most one label from each configured label group may be selected.; csv

Type: `string`. Optional.

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

##### `--start-precision`

Presentation precision for the planned start date. null leaves the precision unspecified.; enum: day|month|quarter|half_year|year; (use "null" or "reset" to clear)

Type: `string`. Optional.

```bash title="terminal"
orc projects create --start-precision <value>
```

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

Presentation precision for the target date. null leaves the precision unspecified.; enum: day|month|quarter|half_year|year; (use "null" or "reset" to clear)

Type: `string`. Optional.

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

##### `--summary`

Short project summary, separate from the detailed description. Null or empty clears it.; (use "null" or "reset" to clear); max 1000 chars

Type: `string`. Optional.

```bash title="terminal"
orc projects create --summary <value>
```

##### `--description`

Optional description.

Type: `string`. Optional.

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

##### `--workspace-id`

Workspace context. Organization-scoped credentials must supply a workspace in their organization. Workspace-scoped API keys remain bound to their authenticated workspace; this value cannot redirect them to another workspace.

Type: `string`. Optional.

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

##### `--initiative-id`

Optional parent Initiative ID in the same Workspace.; (use "null" or "reset" to clear)

Type: `string`. Optional.

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

##### `--milestone`

Optional embedded project milestone. Supply both name and date; omission or null stores no milestone. This does not create a record in the project milestones collection.

Type: `string`. Optional.

```bash title="terminal"
orc projects create --milestone <value>
```

##### `--display-order`

Project list ordering value; smaller values come first and equal values are ordered by projectKey. Creation appends after the current largest value when omitted.

Type: `number`. Optional.

```bash title="terminal"
orc projects create --display-order <value>
```

##### `--color-token`

Visual identity color token. Creation defaults to default when omitted.; enum: default|gray|brown|orange|yellow|green|blue|purple|pink|red

Type: `string`. Optional.

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

##### `--identity-kind`

Visual identity mode. Creation defaults to initial when omitted.; enum: color|initial|icon|emoji|image

Type: `string`. Optional.

```bash title="terminal"
orc projects create --identity-kind <value>
```

##### `--icon-token`

Icon token used with identity_kind=icon. null clears the stored token.; (use "null" or "reset" to clear); max 64 chars

Type: `string`. Optional.

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

##### `--emoji`

Emoji used with identity_kind=emoji. null clears the stored emoji.; (use "null" or "reset" to clear); max 32 chars

Type: `string`. Optional.

```bash title="terminal"
orc projects create --emoji <value>
```

##### `--image-file-id`

Uploaded image file id used with identity_kind=image. null clears the reference.; (use "null" or "reset" to clear)

Type: `string`. Optional.

```bash title="terminal"
orc projects create --image-file-id <value>
```

### `get`

Retrieves details by the Project lookup key. For organization-scoped credentials, specify the target Workspace with `--workspace-id` when needed.

```bash title="terminal"
orc projects get <key> [options]
```

#### Unique options

##### `--workspace-id`

Workspace context. Organization-scoped credentials must supply a workspace in their organization. Workspace-scoped API keys remain bound to their authenticated workspace; this value cannot redirect them to another workspace.

Type: `string`. Optional.

```bash title="terminal"
orc projects get <key> --workspace-id <value>
```

### `update`

Updates the name, status, priority, lead, dates, display order, appearance, or Initiative association. `visibility` stores `workspace` or `private` metadata, but reads in this API are authorized at Workspace level; `private` does not create a separate member access boundary.

```bash title="terminal"
orc projects update <key> [options]
```

#### Unique options

##### `--workspace-id`

Workspace context. Organization-scoped credentials must supply a workspace in their organization. Workspace-scoped API keys remain bound to their authenticated workspace; this value cannot redirect them to another workspace.

Type: `string`. Optional.

```bash title="terminal"
orc projects update <key> --workspace-id <value>
```

##### `--name`

Project display name.

Type: `string`. Optional.

```bash title="terminal"
orc projects update <key> --name <value>
```

##### `--status`

Project lifecycle status. Omitted on creation, it defaults to planned.; enum: planned|in_progress|paused|completed|canceled

Type: `string`. Optional.

```bash title="terminal"
orc projects update <key> --status <value>
```

##### `--priority`

Project priority; null means unassigned.; enum: urgent|high|medium|low; (use "null" or "reset" to clear)

Type: `string`. Optional.

```bash title="terminal"
orc projects update <key> --priority <value>
```

##### `--lead-id`

Active workspace member id of the project lead. null means no lead is assigned.; (use "null" or "reset" to clear)

Type: `string`. Optional.

```bash title="terminal"
orc projects update <key> --lead-id <value>
```

##### `--start-date`

Planned start as YYYY, YYYY-MM or YYYY-MM-DD. This is a calendar value, not a timestamp. null clears it.; (use "null" or "reset" to clear)

Type: `string`. Optional.

```bash title="terminal"
orc projects update <key> --start-date <value>
```

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

Target completion as YYYY, YYYY-MM or YYYY-MM-DD. This is a calendar value, not a timestamp. null clears it.; (use "null" or "reset" to clear)

Type: `string`. Optional.

```bash title="terminal"
orc projects update <key> --target-date <value>
```

##### `--member-ids`

Active workspace member ids assigned to this project. The array replaces the current assignment on update; an empty array clears it. These assignments do not define the workspace access boundary.; csv

Type: `string`. Optional.

```bash title="terminal"
orc projects update <key> --member-ids <value>
```

##### `--labels`

Project label values. The array replaces current labels on update; an empty array clears them. At most one label from each configured label group may be selected.; csv

Type: `string`. Optional.

```bash title="terminal"
orc projects update <key> --labels <value>
```

##### `--start-precision`

Presentation precision for the planned start date. null leaves the precision unspecified.; enum: day|month|quarter|half_year|year; (use "null" or "reset" to clear)

Type: `string`. Optional.

```bash title="terminal"
orc projects update <key> --start-precision <value>
```

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

Presentation precision for the target date. null leaves the precision unspecified.; enum: day|month|quarter|half_year|year; (use "null" or "reset" to clear)

Type: `string`. Optional.

```bash title="terminal"
orc projects update <key> --target-precision <value>
```

##### `--summary`

Short project summary, separate from the detailed description. Null or empty clears it.; (use "null" or "reset" to clear); max 1000 chars

Type: `string`. Optional.

```bash title="terminal"
orc projects update <key> --summary <value>
```

##### `--description`

Project description.

Type: `string`. Optional.

```bash title="terminal"
orc projects update <key> --description <value>
```

##### `--display-order`

Project list ordering value; smaller values come first and equal values are ordered by projectKey. Creation appends after the current largest value when omitted.

Type: `number`. Optional.

```bash title="terminal"
orc projects update <key> --display-order <value>
```

##### `--visibility`

Stored project visibility metadata. Project reads in this API are authorized at workspace level; private does not create a separate member access boundary.; enum: workspace|private

Type: `string`. Optional.

```bash title="terminal"
orc projects update <key> --visibility <value>
```

##### `--color-token`

Visual identity color token. Creation defaults to default when omitted.; enum: default|gray|brown|orange|yellow|green|blue|purple|pink|red

Type: `string`. Optional.

```bash title="terminal"
orc projects update <key> --color-token <value>
```

##### `--identity-kind`

Visual identity mode. Creation defaults to initial when omitted.; enum: color|initial|icon|emoji|image

Type: `string`. Optional.

```bash title="terminal"
orc projects update <key> --identity-kind <value>
```

##### `--icon-token`

Icon token used with identity_kind=icon. null clears the stored token.; (use "null" or "reset" to clear); max 64 chars

Type: `string`. Optional.

```bash title="terminal"
orc projects update <key> --icon-token <value>
```

##### `--emoji`

Emoji used with identity_kind=emoji. null clears the stored emoji.; (use "null" or "reset" to clear); max 32 chars

Type: `string`. Optional.

```bash title="terminal"
orc projects update <key> --emoji <value>
```

##### `--image-file-id`

Uploaded image file id used with identity_kind=image. null clears the reference.; (use "null" or "reset" to clear)

Type: `string`. Optional.

```bash title="terminal"
orc projects update <key> --image-file-id <value>
```

##### `--initiative-id`

Optional parent Initiative ID in the same Workspace.; (use "null" or "reset" to clear)

Type: `string`. Optional.

```bash title="terminal"
orc projects update <key> --initiative-id <value>
```

##### `--milestone`

Embedded project milestone. Omit to preserve it, send null to clear it, or send both name and date to replace it. This does not update records managed by the project milestones collection.

Type: `string`. Optional.

```bash title="terminal"
orc projects update <key> --milestone <value>
```

### `restore`

Restores an archived Project by its lookup key.

```bash title="terminal"
orc projects restore <key> [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 projects restore <key> --idempotency-key <value>
```

### `archive`

Archives a Project by its lookup key. For organization-scoped credentials, specify the containing Workspace with `--workspace-id`.

```bash title="terminal"
orc projects archive <key> [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 projects archive <key> --idempotency-key <value>
```

##### `--workspace-id`

Workspace context. Organization-scoped credentials must supply a workspace in their organization. Workspace-scoped API keys remain bound to their authenticated workspace; this value cannot redirect them to another workspace.

Type: `string`. Optional.

```bash title="terminal"
orc projects archive <key> --workspace-id <value>
```

### `rollup get`

Retrieves a progress rollup using a Project ID or an existing Project key. This is separate from retrieving individual Project settings.

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

## Examples

### Create a Project with a lookup key and name.

```bash title="terminal"
orc projects create --project-key launch-plan --name "Launch plan" --json
```

*Create a Project with a lookup key and name.*

### Mark the Project as in progress.

```bash title="terminal"
orc projects update launch-plan --status in_progress --json
```

*Mark the Project as in progress.*

### Retrieve the progress rollup.

```bash title="terminal"
orc projects rollup get launch-plan --json
```

*Retrieve the progress rollup.*

### Restore an archived Project.

```bash title="terminal"
orc projects restore launch-plan --json
```

*Restore an archived Project.*

## Project keys and membership

`project_key` cannot contain `/`, `\`, or consecutive `..`. The `project_id` used to associate an Issue with a Project is a UUID and differs from this lookup key. Initiative associations must remain within the same Workspace; clear one by sending `null` for `initiative_id` in an update body. Use `orc projects milestones` for milestone management.

## Global Options

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

- [`--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)