c1i command reference

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.

Overview

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

c1i [command]

Command	Subcommands	Description
`docs`	`search` `page` `endpoints` `endpoint` `openapi` `skill`	Explore API documentation (no auth required).
`auth`	`login` `logout` `status` `whoami` `token`	Manage authentication.
`users`	`list`	Search and list C1 users.
`apps`	`list` `create` `delete` `set-owners`	Manage 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.
`policies`	`list` `search` `get` `create` `update` `delete` `validate-cel`	Manage policies (approval, provisioning, and certification workflows).
`mcp`	`gateway list-tools` `gateway call`	Call the C1 MCP gateway directly (list and invoke tools end to end).
`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:

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:

c1i docs search <query>

`page`

Fetch a full documentation page by path. Usage:

c1i docs page <path>

`endpoints`

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

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:

c1i docs endpoint <path>

`openapi`

Dump the raw OpenAPI spec in YAML format. Usage:

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:

c1i docs skill

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

Examples:

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

Auth

Manage authentication credentials. Usage:

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.
`token`	Print a short-lived OAuth2 bearer token for driving raw API calls yourself.

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

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:

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

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:

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:

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.

`token`

Mint and print a short-lived OAuth2 bearer token from your stored credentials, for driving raw API calls yourself (for example, with curl). A new token is minted on each invocation — it is not written to disk. Usage:

c1i auth token [flags]

Flag	Description
`--json`	Also print the token type and absolute expiry (RFC3339), instead of just the access token.

By default only the access token is printed (newline-terminated), so it composes directly into another command:

curl -H "Authorization: Bearer $(c1i auth token)" \
  https://your-tenant.conductor.one/api/v1/apps

The token is audience-scoped to the C1 API host.

Credential storage

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

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.
OS keyring — Keychain (macOS), Credential Manager (Windows), or Secret Service (Linux). Default when available.
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:

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:

c1i users list --email user@example.com

Apps

Manage applications.

`list`

List applications. Outputs NDJSON. Usage:

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.

`create`

Create a new app — a plain, unmanaged container you can register MCP servers under. Only --display-name is required; app owners are managed separately via set-owners, not at create time. Usage:

c1i apps create --display-name <name> [flags]

Flag	Description
`--display-name string`	Display name for the new app. (Required.)
`--description string`	Description for the new app.

The created app is returned as pretty JSON under an app key. Example:

APP_ID=$(c1i apps create --display-name "Google Workspace" | jq -r .app.id)

`delete`

Soft-delete an app by ID. The app is marked deleted and drops out of normal listings, but the record is retained for audit. Usage:

c1i apps delete <app-id>

`set-owners`

Set the complete list of owners for an app, replacing any existing owners. Usage:

c1i apps set-owners <app-id> --user-id <user-id> [flags]

Flag	Description
`--user-id strings`	C1 user ID to set as owner (repeatable; replaces the full owner list). (Required.)
`--wait`	Block and poll until every requested owner appears, or `--wait-timeout` elapses.
`--wait-timeout duration`	Max time to wait with `--wait` (default `4m`).

Owner changes are provisioned asynchronously — this command returns as soon as the request is accepted, but the new owners can take up to a few minutes to actually appear. Pass --wait to block until they do. Example:

c1i apps set-owners app_abc123 --user-id user_1 --user-id user_2 --wait

Accounts

Manage application accounts (app users).

`list`

Search and list accounts for an application. Outputs NDJSON. Usage:

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:

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:

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:

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:

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:

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:

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:

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:

c1i requests create [command]

`create grant`

Create a grant access request. Usage:

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:

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:

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.

Policies

Manage policies — the objects that describe how C1 processes a task (an access request, a certification, a provisioning action): who approves it, what happens on escalation or timeout, and how the underlying resource gets provisioned. Usage:

c1i policies [command]

Subcommand	Description
`list`	List all policies.
`search`	Search policies by display name, description, type, or deletion state.
`get`	Get a single policy by ID.
`create`	Create a new policy.
`update`	Update a policy.
`delete`	Soft-delete a policy.
`validate-cel`	Check a CEL condition for compile errors.

Creating or updating a policy with an empty (or missing) steps list succeeds with no validation error, and silently produces a deny-everything policy. The create and update commands refuse to send a request with empty or missing steps unless you pass --allow-deny-all to confirm that’s what you want.

A policy’s shape is deeply nested: policySteps holds an ordered list of steps, each one of several types (approval, accept, reject, wait, form), and an approval step’s approver is itself one of several kinds (users, manager, group, app owners, self, entitlement owners, expression, webhook, resource owners, agent). Modeling all of that as flags would be unusable, so create and update take the nested pieces from a JSON file (or - for stdin), while flat top-level fields (display name, description, policy type) stay as flags.

`list`

List every policy in the tenant, auto-paginating through the full result. Outputs NDJSON. Unlike most list commands, this takes no query filter at all — only pagination. Use search for filtering. Usage:

c1i policies list [flags]

Flag	Description
`--page-size int`	Number of results per page (max 100).
`--page-token string`	Pagination token for manual pagination.
`--limit int`	Cap the total number of results emitted (0 = unlimited).

`search`

Search policies by a fuzzy query (display name + description), an exact display-name match, one or more policy types, or include soft-deleted policies. Outputs NDJSON. Usage:

c1i policies search [flags]

Flag	Description
`--query string`	Fuzzy search on display name and description.
`--display-name string`	Exact-ish (case-insensitive) display name match.
`--policy-type strings`	Filter by policy type: `grant`, `revoke`, `certify` (repeatable).
`--include-deleted`	Include soft-deleted policies. This is the only listing command that can find one.
`--exclude-policy-id strings`	Policy ID to exclude from results (repeatable).
`--page-size int`	Number of results per page (5–100).
`--page-token string`	Pagination token for manual pagination.
`--limit int`	Cap the total number of results emitted (0 = unlimited).

`get`

Get a single policy by ID. Usage:

c1i policies get <policy-id>

Unlike list and the default search, get returns a soft-deleted policy too (with deletedAt populated) rather than filtering it out.

`create`

Create a new policy. Usage:

c1i policies create --display-name <name> --policy-type <type> [flags]

Flag	Description
`--display-name string`	Display name for the new policy.
`--description string`	Description for the new policy.
`--policy-type string`	Policy type: `grant`, `revoke`, `certify`.
`--steps-file string`	JSON array: the baseline `policySteps.steps` content (file, or `-` for stdin).
`--rules-file string`	JSON array of routing rules: `[{"condition":"<CEL>","stepKey":"<key>"}]` (file, or `-` for stdin).
`--body-file string`	Full request body, verbatim (file, or `-` for stdin); mutually exclusive with the flags above.
`--allow-deny-all`	Allow creating a policy with no steps (or an explicit deny-all).

The created policy is returned as pretty JSON.

`update`

Update a policy. Usage:

c1i policies update <policy-id> [flags]

Flag	Description
`--display-name string`	New display name.
`--description string`	New description.
`--policy-type string`	New policy type: `grant`, `revoke`, `certify` (rarely changed).
`--steps-file string`	JSON array: replaces the baseline `policySteps.steps` content (file, or `-` for stdin).
`--rules-file string`	JSON array: replaces `rules[]` (file, or `-` for stdin).
`--body-file string`	Full policy JSON object, verbatim (file, or `-` for stdin); requires `--update-mask`.
`--update-mask string`	Comma-separated field paths to update (required with `--body-file`; otherwise derived automatically).
`--allow-deny-all`	Allow leaving or setting a policy with no steps.

Only the fields you pass are changed — this is a partial update, not a full replacement (unless you use --body-file).

`delete`

Soft-delete a policy by ID. The row is retained with deletedAt set — this is not a hard delete, and the policy still returns from get afterward. Usage:

c1i policies delete <policy-id>

A policy referenced by another policy (as a rule’s outcome, or as another policy’s baseline) can’t be deleted while that reference exists — the command reports the referencing policy instead.

`validate-cel`

Check a CEL expression for compile errors, without creating or updating anything. Useful for testing a rule’s condition before using it in create or update. Usage:

c1i policies validate-cel <condition>

Example:

c1i policies validate-cel 'subject.role == "admin"'

Exits 0 for a valid condition, 2 for an invalid one — so c1i policies validate-cel '<cond>' && ... only continues past a condition that compiles.

This validates the CEL environment rules run in (subject, account, entitlement, task) — not the same environment an approval step’s expression approver runs in. An expression that’s valid in one may not compile in the other.

MCP gateway

Call the C1 MCP gateway directly over its MCP transport — the same handshake an MCP host performs — to verify what a registered server actually exposes. This closes the configure-then-verify loop: register a server, approve its tools, then list or call them here.

This covers only the gateway subcommand. c1i mcp also has servers, tools, toolsets, and bindings subcommands for managing the MCP surface itself; those aren’t covered on this page yet.

Usage:

c1i mcp gateway [command]

Subcommand	Description
`list-tools`	List the tools the gateway exposes to you.
`call`	Invoke a tool and print its result.

Flag	Description
`--gateway-url string`	MCP gateway endpoint (default: derived from `--url` by inserting `-mcp` into the host — `https://acme.conductor.one` becomes `https://acme-mcp.conductor.one/v1`).

Authentication uses your stored c1i credentials — the standard API token is accepted by the gateway, so no extra setup is needed.

`list-tools`

Run the MCP handshake against the gateway and list the tools it exposes to you. Outputs NDJSON: one row per tool (name, description). Usage:

c1i mcp gateway list-tools [flags]

Flag	Description
`--full`	Include each tool’s input JSON schema in the row.

`call`

Invoke a tool exposed by the gateway and print its raw MCP result. Usage:

c1i mcp gateway call <tool-name> [flags]

Flag	Description
`--args string`	Tool arguments as a JSON object (for example, `'{"id":"abc"}'`).

Find tool names and their input schemas with c1i mcp gateway list-tools --full. Example:

c1i mcp gateway call my_tool --args '{"id":"abc"}'

API

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

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:

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

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

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:

c1i completion <shell>

Examples:

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

​Overview

​Global flags

​Docs

​search

​page

​endpoints

​endpoint

​openapi

​skill

​Auth

​login

​logout

​status

​whoami

​token

​Credential storage

​Users

​list

​Apps

​list

​create

​delete

​set-owners

​Accounts

​list

​set-owner

​Entitlements

​list

​Tasks

​list

​approve

​deny

​comment

​Requests

​create grant

​create revoke

​Connectors

​list

​Policies

​list

​search

​get

​create

​update

​delete

​validate-cel

​MCP gateway

​list-tools

​call

​API

​Pagination and limits

​Version

​Completion

Overview

Global flags

Docs

`search`

`page`

`endpoints`

`endpoint`

`openapi`

`skill`

Auth

`login`

`logout`

`status`

`whoami`

`token`

Credential storage

Users

`list`

Apps

`list`

`create`

`delete`

`set-owners`

Accounts

`list`

`set-owner`

Entitlements

`list`

Tasks

`list`

`approve`

`deny`

`comment`

Requests

`create grant`

`create revoke`

Connectors

`list`

Policies

`list`

`search`

`get`

`create`

`update`

`delete`

`validate-cel`

MCP gateway

`list-tools`

`call`

API

Pagination and limits

Version

Completion