> ## Documentation Index
> Fetch the complete documentation index at: https://www.c1.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# c1i command reference

> A comprehensive reference for all c1i commands, subcommands, and flags.

<Tip>
  **Key commands:**

  Run `c1i help` in your terminal to show all available commands.

  Run `c1i <command> --help` or `c1i <command> -h` for help with a specific command.
</Tip>

## Overview

c1i interacts with the C1 API to manage users, apps, accounts, entitlements, tasks, and access requests.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i [command]
```

| Command        | Subcommands                                              | Description                                   |
| :------------- | :------------------------------------------------------- | :-------------------------------------------- |
| `docs`         | `search` `page` `endpoints` `endpoint` `openapi` `skill` | Explore API documentation (no auth required). |
| `auth`         | `login` `logout` `status` `whoami`                       | Manage authentication.                        |
| `users`        | `list`                                                   | Search and list C1 users.                     |
| `apps`         | `list`                                                   | List applications.                            |
| `accounts`     | `list` `set-owner`                                       | Manage application accounts.                  |
| `entitlements` | `list`                                                   | Search and list application entitlements.     |
| `tasks`        | `list` `approve` `deny` `comment`                        | Manage access request tasks.                  |
| `requests`     | `create grant` `create revoke`                           | Create access requests.                       |
| `connectors`   | `list`                                                   | List connectors.                              |
| `api`          |                                                          | Make raw C1 API requests.                     |
| `version`      |                                                          | Print the c1i version.                        |
| `completion`   | `bash` `fish` `powershell` `zsh`                         | Generate a shell completion script.           |

## Global flags

| Flag           | Description           |
| :------------- | :-------------------- |
| `--url string` | C1 tenant URL.        |
| `-h`, `--help` | Help for any command. |

## Docs

Explore C1 API documentation and schemas. These commands do **not** require authentication.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i docs [command]
```

| Subcommand  | Description                                            |
| :---------- | :----------------------------------------------------- |
| `search`    | Search C1 documentation by keyword.                    |
| `page`      | Fetch a full documentation page.                       |
| `endpoints` | List all API endpoints.                                |
| `endpoint`  | Show the full request/response schema for an endpoint. |
| `openapi`   | Dump the raw OpenAPI spec (YAML).                      |
| `skill`     | Export documentation for AI agents (SKILL.md format).  |

### `search`

Search C1 documentation by keyword.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i docs search <query>
```

### `page`

Fetch a full documentation page by path.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i docs page <path>
```

### `endpoints`

List all available API endpoints. Optionally filter by a pattern.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i docs endpoints [--filter <pattern>]
```

| Flag              | Description                  |
| :---------------- | :--------------------------- |
| `--filter string` | Filter endpoints by pattern. |

### `endpoint`

Show the full request and response schema for a specific API endpoint.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i docs endpoint <path>
```

### `openapi`

Dump the raw OpenAPI spec in YAML format.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i docs openapi
```

### `skill`

Export a self-contained skill file that teaches AI coding agents how to use c1i. The output covers all commands, output formats, API discovery workflows, and common endpoints.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i docs skill
```

| Flag                    | Description                        |
| :---------------------- | :--------------------------------- |
| `-o`, `--output string` | Write to a file instead of stdout. |

**Examples:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
# Print the skill file to stdout
c1i docs skill

# Write directly to a file for Claude Code
c1i docs skill -o .claude/skills/c1i/SKILL.md

# Write as a Cursor project rule
c1i docs skill -o .cursor/rules/c1i.md
```

For step-by-step setup instructions for Claude Code, Cursor, and other agents, see [Use c1i with AI agents](/product/cli/c1i-agent-skills).

## Auth

Manage authentication credentials.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i auth [command]
```

| Subcommand | Description                                                                         |
| :--------- | :---------------------------------------------------------------------------------- |
| `login`    | Authenticate via browser or API credentials.                                        |
| `logout`   | Remove stored credentials for the current URL.                                      |
| `status`   | Check if valid credentials are stored and report the storage backend.               |
| `whoami`   | Show the authenticated principal's identity, roles, permissions, and feature flags. |

### `login`

Authenticate to C1. Opens a browser for OAuth device flow authorization, or accepts credentials directly.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i auth login [flags]
```

| Flag                     | Description                               |
| :----------------------- | :---------------------------------------- |
| `--url string`           | C1 tenant URL.                            |
| `--client-id string`     | Client ID (for non-interactive auth).     |
| `--client-secret string` | Client secret (for non-interactive auth). |

**Examples:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
# Browser-based login
c1i auth login --url example.conductor.one

# Credential-based login
c1i auth login --client-id <id> --client-secret <secret>
```

For non-interactive scripts and CI environments, you can skip stored credentials entirely by setting `C1I_CLIENT_ID` and `C1I_CLIENT_SECRET` (alongside `C1I_URL`) as environment variables. Both must be set; partial values are ignored. See [Credential storage](#credential-storage) for the full precedence order.

### `logout`

Remove stored c1i credentials for the current URL from both the OS keyring and the file fallback. Environment variables (`C1I_CLIENT_ID`, `C1I_CLIENT_SECRET`) are not affected.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i auth logout
```

### `status`

Check whether valid C1 credentials are stored and working. Reports which source (environment, keyring, or file) served the active credentials.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i auth status
```

### `whoami`

Show the authenticated principal — user ID, display name, email, and counts of roles, permissions, and tenant feature flags. Useful for agents and scripts that need to confirm identity before making other API calls.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i auth whoami [flags]
```

| Flag              | Description                                                     |
| :---------------- | :-------------------------------------------------------------- |
| `-v`, `--verbose` | Include the full `roles`, `permissions`, and `features` arrays. |

By default, `whoami` returns a compact summary. Use `--verbose` when you need the full role and permission lists.

## Credential storage

c1i reads credentials from the first source that has them, in this order:

1. **Environment variables** — `C1I_CLIENT_ID` and `C1I_CLIENT_SECRET` (combined with `C1I_URL`). Both must be set. Used for non-interactive scripts, CI, and containers. Never written to disk.
2. **OS keyring** — Keychain (macOS), Credential Manager (Windows), or Secret Service (Linux). Default when available.
3. **File fallback** — a `0600` JSON file under your config directory:
   * Linux: `~/.config/c1i/credentials/`
   * macOS: `~/Library/Application Support/c1i/credentials/`
   * Windows: `%AppData%\c1i\credentials\`

The file fallback is used automatically when no OS keyring is available — typical on headless Linux servers, Docker or LXC containers, CI runners, and WSL without a desktop environment. `c1i auth login` writes to the keyring when it can and to the file otherwise; `c1i auth status` reports the active source.

## Users

Manage C1 users.

### `list`

Search and list C1 users. Outputs NDJSON.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i users list [flags]
```

| Flag                  | Description                                                                                                                |
| :-------------------- | :------------------------------------------------------------------------------------------------------------------------- |
| `--query string`      | Search query.                                                                                                              |
| `--email string`      | Filter by email address.                                                                                                   |
| `--status string`     | Filter by status: `enabled`, `disabled`, or `deleted`.                                                                     |
| `--page-size int`     | Number of results per page (max 100; values higher than 100 are clamped client-side).                                      |
| `--page-token string` | Pagination token for manual pagination.                                                                                    |
| `--limit int`         | Cap the total number of results emitted (0 = unlimited). Auto-pagination stops fetching new pages once the cap is reached. |

**Example:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i users list --email user@example.com
```

## Apps

Manage applications.

### `list`

List applications. Outputs NDJSON.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i apps list [flags]
```

| Flag                  | Description                                                                                                                |
| :-------------------- | :------------------------------------------------------------------------------------------------------------------------- |
| `--page-size int`     | Number of results per page (max 100; values higher than 100 are clamped client-side).                                      |
| `--page-token string` | Pagination token for manual pagination.                                                                                    |
| `--limit int`         | Cap the total number of results emitted (0 = unlimited). Auto-pagination stops fetching new pages once the cap is reached. |

## Accounts

Manage application accounts (app users).

### `list`

Search and list accounts for an application. Outputs NDJSON.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i accounts list --app-id <app-id> [flags]
```

| Flag                  | Description                                                                                                                |
| :-------------------- | :------------------------------------------------------------------------------------------------------------------------- |
| `--app-id string`     | Application ID. (Required.)                                                                                                |
| `--status string`     | Filter by status.                                                                                                          |
| `--type string`       | Filter by type: `user`, `service_account`, or `system_account`.                                                            |
| `--unmapped-only`     | Only show unmapped accounts.                                                                                               |
| `--query string`      | Search query.                                                                                                              |
| `--page-size int`     | Number of results per page (max 100; values higher than 100 are clamped client-side).                                      |
| `--page-token string` | Pagination token for manual pagination.                                                                                    |
| `--limit int`         | Cap the total number of results emitted (0 = unlimited). Auto-pagination stops fetching new pages once the cap is reached. |

### `set-owner`

Set the owner of an application account.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i accounts set-owner --app-id <app-id> --app-user-id <app-user-id> --user-id <user-id>
```

| Flag                   | Description                             |
| :--------------------- | :-------------------------------------- |
| `--app-id string`      | Application ID. (Required.)             |
| `--app-user-id string` | App user ID. (Required.)                |
| `--user-id string`     | C1 user ID to set as owner. (Required.) |

## Entitlements

Manage application entitlements.

### `list`

Search and list application entitlements. Outputs NDJSON.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i entitlements list [flags]
```

| Flag                  | Description                                                                                                                |
| :-------------------- | :------------------------------------------------------------------------------------------------------------------------- |
| `--app-id string`     | Filter by application ID.                                                                                                  |
| `--query string`      | Search query.                                                                                                              |
| `--page-size int`     | Number of results per page (max 100; values higher than 100 are clamped client-side).                                      |
| `--page-token string` | Pagination token for manual pagination.                                                                                    |
| `--limit int`         | Cap the total number of results emitted (0 = unlimited). Auto-pagination stops fetching new pages once the cap is reached. |

## Tasks

Manage access request tasks.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i tasks [command]
```

| Subcommand | Description              |
| :--------- | :----------------------- |
| `list`     | Search and list tasks.   |
| `approve`  | Approve a task.          |
| `deny`     | Deny a task.             |
| `comment`  | Add a comment to a task. |

### `list`

Search and list access request tasks. Outputs NDJSON.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i tasks list [flags]
```

| Flag                  | Description                                                                                                                |
| :-------------------- | :------------------------------------------------------------------------------------------------------------------------- |
| `--state string`      | Filter by state: `open` or `closed`.                                                                                       |
| `--query string`      | Search query.                                                                                                              |
| `--assigned-to-me`    | Only show tasks assigned to the current user.                                                                              |
| `--page-size int`     | Number of results per page (max 100; values higher than 100 are clamped client-side).                                      |
| `--page-token string` | Pagination token for manual pagination.                                                                                    |
| `--limit int`         | Cap the total number of results emitted (0 = unlimited). Auto-pagination stops fetching new pages once the cap is reached. |

### `approve`

Approve an access request task.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i tasks approve --task-id <task-id> [flags]
```

| Flag               | Description                           |
| :----------------- | :------------------------------------ |
| `--task-id string` | Task ID. (Required.)                  |
| `--comment string` | Comment to include with the approval. |

### `deny`

Deny an access request task.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i tasks deny --task-id <task-id> [flags]
```

| Flag               | Description                         |
| :----------------- | :---------------------------------- |
| `--task-id string` | Task ID. (Required.)                |
| `--comment string` | Comment to include with the denial. |

### `comment`

Add a comment to a task.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i tasks comment --task-id <task-id> --comment <comment>
```

| Flag               | Description               |
| :----------------- | :------------------------ |
| `--task-id string` | Task ID. (Required.)      |
| `--comment string` | Comment text. (Required.) |

## Requests

Create access requests.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i requests create [command]
```

### `create grant`

Create a grant access request.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i requests create grant --app-id <app-id> --entitlement-id <entitlement-id> [flags]
```

| Flag                      | Description                         |
| :------------------------ | :---------------------------------- |
| `--app-id string`         | Application ID. (Required.)         |
| `--entitlement-id string` | Entitlement ID. (Required.)         |
| `--user-id string`        | User ID (defaults to current user). |
| `--duration string`       | Requested access duration.          |
| `--description string`    | Justification for the request.      |
| `--emergency`             | Request emergency access.           |

### `create revoke`

Create a revoke access request.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i requests create revoke --app-id <app-id> --entitlement-id <entitlement-id> [flags]
```

| Flag                      | Description                         |
| :------------------------ | :---------------------------------- |
| `--app-id string`         | Application ID. (Required.)         |
| `--entitlement-id string` | Entitlement ID. (Required.)         |
| `--user-id string`        | User ID (defaults to current user). |
| `--description string`    | Justification for the request.      |

## Connectors

Manage connectors.

### `list`

List connectors for an application. Outputs NDJSON.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i connectors list --app-id <app-id> [flags]
```

| Flag                  | Description                                                                                                                |
| :-------------------- | :------------------------------------------------------------------------------------------------------------------------- |
| `--app-id string`     | Application ID. (Required.)                                                                                                |
| `--page-size int`     | Number of results per page (max 100; values higher than 100 are clamped client-side).                                      |
| `--page-token string` | Pagination token for manual pagination.                                                                                    |
| `--limit int`         | Cap the total number of results emitted (0 = unlimited). Auto-pagination stops fetching new pages once the cap is reached. |

## API

Make raw C1 API requests. This is an escape hatch for accessing any API endpoint not covered by the built-in commands.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i api --path <path> [flags]
```

| Flag              | Description                                                                                                          |
| :---------------- | :------------------------------------------------------------------------------------------------------------------- |
| `--path string`   | API endpoint path. (Required.)                                                                                       |
| `--method string` | HTTP method: `GET`, `POST`, `PUT`, or `DELETE`. (Default: `GET`.)                                                    |
| `--body string`   | Request body (JSON).                                                                                                 |
| `--paginate`      | Auto-paginate and output results as NDJSON.                                                                          |
| `--limit int`     | With `--paginate`, cap the total number of NDJSON rows emitted (0 = unlimited). Errors if used without `--paginate`. |

**Examples:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
# GET request
c1i api --path /api/v1/apps

# POST request — passing --body switches the method to POST automatically
c1i api --path /api/v1/search/tasks --body '{"taskStates":["TASK_STATE_OPEN"]}'

# Paginate through results as NDJSON
c1i api --path /api/v1/apps --paginate

# Paginate a POST search endpoint
c1i api --path /api/v1/search/tasks --body '{"taskStates":["TASK_STATE_OPEN"]}' --paginate
```

If you call a POST-only endpoint with GET (for example a `/search/*` path with no `--body`), c1i prints a one-line hint suggesting `--body` or `--method=POST` so you can recover without consulting the schema.

## Pagination and limits

c1i list commands (and `c1i api --paginate`) auto-paginate by default — they keep fetching pages until the cursor is empty, so you don't have to manage tokens manually.

Three flags control how much data flows:

| Flag                 | Effect                                                                                                                                                                                                                                                          |
| :------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--page-size N`      | Per-call batch size. The C1 API caps this at 100; c1i clamps client-side, so `--page-size 500` is treated as 100. Default is 50.                                                                                                                                |
| `--page-token TOKEN` | Resume from a specific cursor. When set, c1i fetches a single page and exits — auto-pagination is disabled.                                                                                                                                                     |
| `--limit N`          | Cap the *total* number of results emitted across all pages (0 = unlimited). Auto-pagination stops fetching new pages once the cap is reached, and c1i tightens the per-call request size when `--limit` is smaller than `--page-size` so it doesn't over-fetch. |

**Examples:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
# Peek at the first 5 users without fetching everyone
c1i users list --limit 5

# Cap a wide query — useful for cost control or quick previews
c1i tasks list --state open --limit 25

# --limit also works with the raw api command, but only with --paginate
c1i api --path /api/v1/search/tasks --body '{"taskStates":["TASK_STATE_OPEN"]}' --paginate --limit 10
```

`c1i api --path X --limit N` without `--paginate` errors immediately — the non-paginated path returns a single response, so there's nothing to cap.

## Version

Print the c1i version.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i version
```

You can also use `c1i --version`.

## Completion

Generate a shell completion script. Output is the script itself, which you can write to a file or `source` directly. Supported shells are bash, zsh, fish, and PowerShell.

**Usage:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
c1i completion <shell>
```

**Examples:**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
# bash
c1i completion bash > /etc/bash_completion.d/c1i

# zsh
c1i completion zsh > "${fpath[1]}/_c1i"

# fish
c1i completion fish > ~/.config/fish/completions/c1i.fish

# PowerShell
c1i completion powershell > $PROFILE
```

For shell-specific install steps, run `c1i completion <shell> --help`.