Skip to main content
This reference reflects c1i v0.11.0. The CLI is authoritative: run c1i <command> --help (or -h) for the exact flags. In builds that include c1i docs map, its default outline and --json tree list every command path and count for a quick comparison.

Overview of c1i commands

Use this reference to find the command, flags, and output format for any c1i task, from managing identities, apps, and access to policies, automations, and MCP servers. List and search commands output NDJSON, one JSON object per line. Other commands output formatted JSON. An absent string field in a list row is null, not "". Mutation commands, such as apps create, requests create grant, and tasks approve, print the API’s response unwrapped the same way the matching get command unwraps it, so you read an ID with .id rather than .app.id. Deletes and other empty responses print {}; exit 0 means success. A few responses carry a different ID path, such as .connectorId for an MCP server. See Output conventions for auth, docs, and api output.

Common workflows

Find the command to start with for a common c1i task.

Global flags

Every command accepts these flags. Each global flag also reads a C1I_* environment variable: C1I_URL, C1I_FIELDS, C1I_MAX_RETRIES, C1I_ERROR_FORMAT, C1I_DRY_RUN, and C1I_DEBUG. A flag on the command line overrides its variable. A non-empty C1I_DRY_RUN, C1I_DEBUG, C1I_MAX_RETRIES, or C1I_ERROR_FORMAT value that doesn’t parse exits with code 2 before any request, as does a negative --max-retries.

Dry run

--dry-run (or C1I_DRY_RUN=1) previews a C1 REST mutation and sends nothing. The preview is one JSON object on stdout with two keys, dryRun and requests. requests lists each request in send order, with its method, full url, and the body as sent (omitted when the request has no body). A notice on stderr, dry run: nothing was sent, accompanies every preview.
  • Credential fields appear as [redacted]: fields whose names end in token, secret, password, signature, or apikey, header values, a URL’s username or password, and secret-named URL parameters. A body that isn’t JSON prints as "[redacted: not JSON]".
  • A preview needs a configured URL (exit 2 without one), and an empty, ., or .. ID is refused with exit 2, as it is for a real request. A preview needs no credentials unless c1i must look something up: a task’s current policy step, a hosted MCP server’s catalog ID, the caller for requests create, or a referenced user, policy, or app account checked before sending. Those checks run on a preview too, so the preview needs the matching read access.
  • A preview has no id. If an inherited C1I_DRY_RUN=1 turns a script’s writes into previews, jq -r .id prints null and the script carries on. Extract IDs with jq -er, which fails on a preview.
  • upgrade --dry-run follows the same JSON preview shape: dryRun, requests, and an upgrade object with the --check fields. upgrade --fields is a usage error unless you pass --check.

Errors and exit codes

On failure, c1i writes an error to stderr and exits with a code you can branch on. A token-endpoint failure follows the same classification as other responses: 400/401/403 exits 3, 404 exits 4, 408 exits 1, 429 exits 5, and a 5xx or unusable 200 exits 6. An unreachable token endpoint is a transport failure (exit 1), not bad credentials. Several writes look up referenced users or policies before sending. An unknown referenced id exits 4; a policy that exists but is deleted or of the wrong type exits 2. The same checks run under --dry-run, so a preview can need the corresponding read access. With --error-format json, stderr is NDJSON: each line is one object with an error, notice, progress, or debug key. Select errors with jq 'select(.error)'. API errors include status, method, path, and body. An error from a command that writes also carries "applied": false when nothing reached the server, true when the change was applied, and "unknown" when the request may have reached the server, including when a retry then failed. mcp tools approve adds an error object for each failed ID and a summary object with notAttempted. A batch can exit non-zero after it applied some changes.

Docs

Explore C1 API documentation and schemas. These commands don’t require authentication. docs endpoints, docs endpoint, and docs openapi read the public spec at https://www.c1.ai/api/openapi.yaml, which includes the MCP, service principal, and access review operations. c1i caches the spec for 24 hours at ~/.c1i/cache/api-openapi.yaml. If a fetch fails, c1i serves the stale cache and prints a one-line warning on stderr. Each refresh deletes other files in ~/.c1i/cache/, so keep your own files elsewhere. docs search and docs page exit with code 8 when the documentation site fails, whatever the cause: an unreachable site, a non-200 response, an unparseable body, or a redirect loop. With no cached spec to fall back on, a redirect loop on docs openapi, docs endpoints, or docs endpoint also exits 8.

docs guide

Print an embedded, task-oriented runbook: a numbered sequence of c1i commands for a common end-to-end workflow. Run it with no argument to list the available guide names and their purposes. Guides are static content in the c1i binary, so unlike docs search and docs page they make no network call. Usage:

docs agents

Print a concise, agent-facing document covering the conventions that --help text can’t: getting the tenant right, output contracts, exit codes, pagination, and when to prefer a first-class command over c1i api. It doesn’t list every command or flag; run c1i --help, c1i <group> --help, or c1i <group> <command> --help for those. The output opens with a YAML front-matter block (name, description, version, and required binaries) that some agent harnesses parse automatically, followed by plain Markdown. skill remains an alias for backward compatibility, so c1i docs skill still works. Examples:
For step-by-step setup instructions for Claude Code, Cursor, and other agents, see Use c1i with AI agents.

docs readme and docs changelog

Print the README or CHANGELOG embedded in the c1i binary, unmodified. They make no network call and need no credentials. Release archives ship only the binary, so these are how an installed c1i reads its own full reference. docs agents stays the concise guide for agents; the README is the full reference. Relative links in the printed text don’t resolve. A notice on stderr gives the version-pinned GitHub URL that renders the Markdown.
These examples use conductor.one. If your organization is on the EU data residency instance, substitute c1eu.ai in URLs, client IDs, and hostnames.

Auth

Log in, check which identity and credential c1i is using, and mint access tokens. c1i reads credentials from C1I_CLIENT_ID and C1I_CLIENT_SECRET, then the OS keyring, then a 0600 file, and caches each access token it mints until it’s close to expiry; see Credential storage. auth token and mcp gateway always mint a fresh token. A cached token the server rejects (clock skew, or a revocation) is dropped and re-minted automatically, once.

auth login

Opens a browser for OAuth device flow authorization, or accepts credentials directly. A browser login creates a credential with all of your roles; see Limit the credential to specific roles. --scoped-role takes a role name or a role ID from c1i roles list. A name that matches no role you can scope to exits with code 2 before c1i creates your credential. An unknown role ID exits with code 4. --choose-roles and --scoped-role can’t be combined, and neither works with --client-id and --client-secret. auth login rejects --dry-run (exit 2), because it can’t preview creating a credential.

auth whoami

Show the authenticated principal: principal ID, user ID (a service principal might carry only the principal ID), counts of roles, permissions, and tenant feature flags, and display name and email when the user lookup succeeds. By default, whoami returns a compact summary. --verbose replaces that summary with the raw introspect payload, which includes the full role, permission, and feature lists but not the summary’s counts, displayName, or email. Both modes add two keys that c1i resolves itself: tenant, the base URL this invocation targets, and tenantSource, where it came from (flag, env, or config). They appear only after your credentials are proven against that tenant, so check them before a write:

auth token

c1i mints a new token from your stored credentials on each invocation and doesn’t write it to disk. By default only the access token is printed (newline-terminated), so it composes directly into another command:
The token is audience-scoped to the C1 API host.

Roles

List and inspect IAM roles, including the role IDs that c1i auth login --scoped-role accepts.

Users

Manage C1 users.

users list

Paginates. With no --origin, the list includes only directory-origin users. It omits local-origin users, such as service principals, and system users. Pass --origin all to list every user. Rows carry origin when the server reports one.

Apps

Create, inspect, update, and delete applications, manage their owners, and promote apps a connector discovered.

apps create

Create a new app — a plain, unmanaged container you can register MCP servers under. Only --display-name is required. C1 assigns the caller as an owner of the new app; manage owners afterward with add-owner, remove-owner, or set-owners. Usage:
Before sending, c1i checks each policy ID. An ID that doesn’t exist exits with code 4; one that is deleted or of the wrong type exits with code 2. Nothing is sent. --dry-run runs the same check. An empty policy ID is a usage error. The created app is returned as formatted JSON, unwrapped like apps get, so the app’s ID is .id. Example:

apps update

Update an app’s display name, description, policies, or identity matching. c1i builds the update mask from the flags you pass: an omitted flag is left alone, and an explicit empty value is a change. Usage:
Each policy ID is checked before anything is sent, as for apps create. An empty policy ID is a usage error rather than an unbind, so pass --unbind-policy to remove a policy. You can’t set and unbind the same kind in one call. --app-user-mapper-file takes an object such as {"mappingCases":[{"userKeyCel":"subject.email","appUserKeyCel":"account.email"}]}. userKeyCel runs against the C1 user as subject, and appUserKeyCel runs against the app user as account. mappingCases must be non-empty, and the API offers no way to remove a mapper. The updated app is returned as formatted JSON, unwrapped like apps get.

apps owners

Paginates. Usage:
Use this to verify an owner change. Owner changes are applied asynchronously and can take several minutes to appear. Most apps already have at least one owner, because apps create assigns its caller as an owner. A well-formed app ID that doesn’t exist returns zero rows and exits 0, not 4.

apps add-owner

Add one user as an app owner without changing the rest of the owner list. Unlike set-owners, it can’t drop an owner that someone else added in the meantime. Usage:
An unknown app or user ID exits with code 4; c1i looks up the --user-id before sending, including under --dry-run. Owner changes are applied asynchronously; verify with c1i apps owners <app-id>. Prints {}; exit 0 means success.

apps remove-owner

Remove one user as an app owner without changing the rest of the owner list. The creator that apps create assigned can remain an owner, so check c1i apps owners <app-id> first if that matters. Usage:
An unknown app ID exits with code 4. Owner changes are applied asynchronously; verify with c1i apps owners <app-id>. Prints {}; exit 0 means success.

apps set-owners

Usage:
Before it sends the request, c1i looks up each distinct --user-id. An unknown user exits with code 4, naming the ID, and nothing is sent. The lookup needs user-read access, so a credential without it exits with code 3. --dry-run runs the same lookups. c1i sends a repeated --user-id once. Owner changes are applied asynchronously, so the command returns once the request is accepted and new owners can take several minutes to appear. Pass --wait to block until the owner set equals the request, including removals. --wait progress goes to stderr, and the command prints the API’s JSON response on stdout. Example:

apps managed-state

Inspect and promote the apps a connector discovered, such as apps in an identity provider’s catalog. A discovered app is a resource of the connector app’s app-trait resource type. Until it is promoted, its state is unmanaged; promote creates a managed app and returns managed with that app’s id. Find the resource type first with apps resource-types list. Every subcommand takes --app-id (the connector app) and --resource-type-id. promote accepts repeatable --user-id to set the new app’s owners; omit it to inherit the connector app’s owners. An unknown app, resource type, resource id, or user exits with code 4, including under --dry-run. Promoting an already-managed binding exits 0 and returns the existing app id. Promoting does not check for an existing app with the same name, so check apps list first if a duplicate name matters. After deleting the managed app, the binding’s deletedAt can lag by a few seconds; wait until managed-state get shows it before promoting again, or you can create a second app.

apps resource-types list

List an app’s resource types. The connector app’s discovered apps are in its app resource type. Usage:
A well-formed but unknown app returns zero rows and exits 0. Paginates.

Accounts

Manage application accounts (app users). Both commands require --app-id, the application ID.

accounts list

Search and list accounts for an application. Paginates. Usage:

accounts set-owner

Set the owner of an application account. Usage:
An unknown app or user exits with code 4; c1i looks up the user before sending, including under --dry-run.

Attribute types

List the user fields an attribute mapping can write to, such as Department, Job Title, or Manager Email. Type ids are tenant-specific, so look a type up by display name; attribute-mappings create --type does the same.

attribute-types list

Usage:
Rows include id, display_name, and config_kind: app, app_user_profile, custom_app_user_profile, or cel_expression. A mapping’s config_kind decides which key flags it accepts. A cel_expression type cannot be created with the convenience flags; use --body-file.

Attribute mappings

Map an app’s synced profile attributes onto C1 user fields. A mapping reads one attribute from an app (or from a user’s app profile) and writes it to a C1 user attribute. Evaluation is asynchronous; there is no completion signal.

attribute-mappings create

Usage:
c1i looks the type up before sending, including under --dry-run: an unknown type exits 4, and a name shared by several types exits 2 with their ids. A second create for the same app and type is not refused; list first in a script. A real run with an unknown app id exits 4; --dry-run looks up the type but not the app, so it can preview a request the server would refuse. Example:

attribute-mappings update

Usage:
The API’s PUT replaces the mapping and ignores updateMask, so c1i reads the current mapping and re-sends its attribute type, fallbacks, and profile types with only these flags changed. The read and write are not atomic; an edit made between them is overwritten. The type and app cannot be changed.

Entitlements

Find, inspect, create, update, and delete app entitlements, manage their owners, and link entitlements to each other with proxy bindings. An entitlement ID is only unique within an app, so always key on the app ID and the entitlement ID together. Some built-in entitlements, such as the base Access entitlement, use the same ID in every app that has one.

entitlements list

Paginates.

entitlements get

Usage:

entitlements create

Create an app entitlement, plus the app resource type and resource it points at, as up to three requests in order. Pass --resource-type-id to reuse an existing resource type, and --resource-id to reuse an existing resource. Outputs the created entitlement as formatted JSON, unwrapped like entitlements get, so its ID is .id. The output echoes appResourceTypeId and appResourceId and expands both objects. Usage:
Passing --resource-type or --resource-type-display-name together with --resource-type-id is a usage error (exit 2), as is --resource-id without --resource-type-id. Only the CUSTOM resource type can repeat on one app, so reuse an existing type with --resource-type-id for any other kind. Before the first request, c1i checks each policy ID and each --owner-id. An unknown policy or user exits with code 4 and creates nothing; a policy that is deleted or of the wrong type exits with code 2. The owner check reads the user, so a credential without user-read access exits with code 3. c1i sends a repeated --owner-id once. --dry-run runs the same checks. There is no rollback. If a later request fails, the objects that earlier ones created still exist; the error names them and the flags that reuse them. --dry-run previews every request in the sequence, and where an ID exists only after an earlier request, the preview shows NEW_APP_RESOURCE_TYPE_ID or NEW_APP_RESOURCE_ID in its place. Owner changes are applied asynchronously. Example:

entitlements update

Update an entitlement’s display name, description, policies, or maximum grant duration. c1i builds the update mask from the flags you pass, so an omitted flag is left alone. Usage:
Each policy ID is checked before anything is sent. An ID that doesn’t exist exits with code 4; one that is deleted or of the wrong type exits with code 2. An empty policy ID is a usage error rather than an unbind, so pass --unbind-policy to remove a policy. --dry-run runs the same check. --emergency-grant-enabled needs --emergency-grant-policy-id in the same call, even when the entitlement already has a policy stored, or c1i exits with code 2. The server doesn’t refuse unbinding the emergency policy while emergency grants stay enabled, so pass --emergency-grant-enabled=false alongside --unbind-policy emergency-grant. The updated entitlement is returned as formatted JSON, unwrapped like entitlements get. Example:

entitlements delete

Delete an app entitlement. The delete is soft: entitlements get still returns the entitlement with deletedAt set. apps delete leaves an app’s entitlements live, so delete them with this command first. Prints {}; exit 0 means success. Usage:

entitlements owners

List an entitlement’s owners as NDJSON, in the same row shape as apps owners. Paginates. Usage:
Use this to verify an owner change. Owner changes are applied asynchronously and can take several minutes to appear. A well-formed entitlement or app ID that doesn’t exist returns zero rows and exits 0, so an empty result means either no owners or a wrong ID.

entitlements add-owner

Add one user as an entitlement owner without changing the rest of the owner list. Adding a user who is already an owner exits 0. Usage:
An unknown user, entitlement, or app exits with code 4. A --wait that reaches --wait-timeout exits with code 1, though the write was accepted. --wait progress goes to stderr, and the command prints the API’s JSON response on stdout. With --dry-run, --wait never polls.

entitlements remove-owner

Remove one user as an entitlement owner without changing the rest of the owner list. Unlike set-owners, it can remove the last owner. Usage:
A user who was never an owner exits with code 4, the same as an unknown user, entitlement, or app, so exit 4 can’t tell those cases apart. A user who was an owner and is already removed exits 0. Prints {}; exit 0 means success.

entitlements set-owners

Set the complete list of owners for an entitlement, replacing any existing owners. It refuses an empty list, because the API treats an empty list as “remove every owner.” Usage:
Before it sends the request, c1i looks up each distinct --user-id. An unknown user exits with code 4, naming the ID, and nothing is sent, because the API would accept the unknown ID and silently drop it, possibly leaving no owners. The lookup needs user-read access. --dry-run runs the same lookups. c1i sends a repeated --user-id once, because the API answers a duplicate with a 500.

entitlements proxy-bindings

A proxy binding is a visibility and tracking link from a source entitlement to a destination entitlement — it does not grant access or configure delegated provisioning. The public REST API has no list endpoint for proxy bindings; the C1 Console discovers them through an internal search service that isn’t part of the public API. Each subcommand takes the same four flags to identify the binding: Usage:

Grants

Query access grants, the bindings between accounts or users and entitlements, to answer “who has access to what”. You can also add users directly to a manually managed entitlement.

grants list

Search and list grants. At least one filter is required. Paginates. Grant provisioning is asynchronous, so a read taken right after a grant or revoke can catch the set mid-change. With --wait, c1i re-reads every page of the match every 5 seconds, regardless of --limit, and prints the settled set; progress goes to stderr, so stdout stays pure NDJSON. An empty result is stable: if you are waiting for a grant you just made, pass --wait-min 1 so the wait holds out for it instead of settling on zero rows. Example:

grants add

Grant users a manually managed entitlement directly. This bypasses the entitlement’s grant policy and approval, so no access-request task is created. For a policy-respecting request, use requests create grant instead. Usage:
c1i looks up each --user-id before sending, including under --dry-run; an unknown user exits 4 and nothing is sent. A repeated --user-id is sent once. Adding a user who already holds the entitlement exits 0. The server’s failedUsersErrorMap is printed when present, each rejected user is named, and the command exits 1; --wait then waits only for the users that were accepted. There is no grants remove. Direct removal (remove-membership) rejects a manually managed entitlement; remove access through requests create revoke.

Tasks

List access request tasks and act on them: approve, deny, comment, reassign, or move them through their policy.

tasks list

Paginates.

tasks get

Get a single task by ID: the full task view, including its current policy step and outcome, as formatted JSON. It reads the same endpoint as c1i requests get, because access requests are tasks. Use it to re-read a task after an action, since action output reports the task’s state from before the action. Usage:

tasks approve

Usage:
If you omit --policy-step-id, c1i fetches and uses the task’s currently executing step. If the task has no current step, the command exits with code 2 and tells you to re-read the task with c1i tasks get; --policy-step-id can’t supply a step the task doesn’t have.

tasks deny

Usage:
Unlike approve, deny doesn’t require a step: if the task has no current step, c1i sends the denial without one. deny and restart on an unknown task exit with code 4 and send nothing.

tasks comment

Usage:

tasks close

Closing cancels the task and records no approval decision; use approve or deny to record an outcome. Usage:

tasks process

Use it on a task that looks stuck; it asks C1 to re-run policy evaluation without changing the task’s approval state. Usage:
Processing is asynchronous. Re-read the task with c1i tasks get <task-id> to see the result.

tasks reassign

--to-user-id sets the step’s approvers to the users you name. Usage:

tasks reset

Unlike restart, which re-runs the current step, reset discards the task’s approval progress and starts the policy over. It takes no policy step. Usage:

tasks restart

On an open task, this rotates the current policy step and records the restart in the task’s policy history. It doesn’t reopen a closed task. Whether restart is available depends on the task; the server otherwise refuses with action not permitted. Usage:
restart, reset, and skip-step each rotate the current policy step, so a --policy-step-id captured before one of them goes stale and the server answers this action is no longer available. Omit the flag to act on whatever step is current.

tasks skip-step

Usage:
skip-step refuses the current step when it is not an approval step (exit 2, nothing sent). Skipping a provisioning step abandons provisioning and can leave the task stranded or close it. Pass --policy-step-id explicitly only if you intend to skip that step.

tasks update-grant-duration

The task must still be at an approval step; once it reaches provisioning, the server refuses with cannot update grant duration for a ticket in a provision step. Usage:
The new value lands at .type.grant.grantDuration on the task; read it back with c1i tasks get <task-id>.
Every task action prints the task as formatted JSON, unwrapped like tasks get, so the task’s ID is .id. The action endpoints return the task as it was before the action, so .state is a snapshot, not the outcome: closing an open task prints an open state. Re-read the task with c1i tasks get before you act on it. When c1i looks up a policy step for you, it reports the step on stderr (Resolved policy step: <id>) rather than in the JSON.

Requests

File grant and revoke requests, track their status, and optionally wait for the created grant.

requests list

List access requests: the grant and revoke tasks a requester files. By default it shows requests you opened or are the subject of, which complements c1i tasks list (the approver’s view). Paginates.

requests create grant

Usage:
With --wait, the task is printed immediately, progress goes to stderr, and c1i reads the matching grant set before sending. A grant the recipient already held does not satisfy the wait; the command waits for a grant that was not there before. A request that needs approval therefore waits to the timeout. A timeout exits 1, though the request was accepted; re-read the task with requests get. --dry-run never polls.

requests create revoke

Usage:
Both create commands print the created task unwrapped like tasks get, so the task’s ID is .id. Its .state is a snapshot from creation, not the outcome. When you omit --user-id, c1i resolves the caller, so a --dry-run preview then needs credentials. An explicit --user-id is looked up before sending; an unknown user exits with code 4, including under --dry-run.

Connectors

Manage connectors.

connectors list

List connectors for an application. Paginates. Usage:

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.
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 seven types (approval, provision, accept, reject, wait, form, action), 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). You can read back all seven types, but create and update refuse two of them client-side with exit code 2, before sending a request: a "provision" step is never allowed in a policy body — it's read-only and server-computed and an "action" step is not supported by create/update yet. Modeling the nested structure 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.

policies list

Paginates. Unlike most list commands, this takes no query filter at all — only pagination. Use search for filtering. Rows carry step_kinds (the kind of each step in the policy’s baseline sequence) and baseline_policy_id, which together identify a tenant’s auto-approval policy without matching on its display name. Search rows carry the same keys. Paginates; --page-size defaults to 25.

policies get

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

policies create

Usage:

policies update

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

policies delete

The row is retained with deletedAt set — this is not a hard delete, and the policy still returns from get afterward. Usage:
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.

policies validate-cel

It creates and updates nothing, so you can test a rule’s condition before using it in create or update. Usage:
Example:
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.

Access profiles

Manage access profiles — the objects that control which entitlements are requestable, and by whom. Admins create them to grant birthright access or to make access requestable by a chosen audience. The API calls this object a request catalog and routes it under /api/v1/catalogs, so its JSON keys and the IDs you pass here say “catalog” — the two names refer to the same object. Not to be confused with an app catalog, the per-user list of what one user can request, derived from the access profiles they belong to.
A profile’s visibility bindings can only be added once it’s published: adding a visibility entitlement to an unpublished profile, or to one that’s --visible-to-everyone, is refused with a 400 (catalog must be published to add an access entitlement / catalog is visible to everyone, cannot add access entitlements). Publish first if you plan to restrict visibility by entitlement.
requestable-entitlements add/remove and visibility-entitlements add/remove take a shared --app-id plus one or more repeatable --entitlement-id flags, since an entitlement reference pairs an entitlement ID with the application that owns it. requestable-entitlements set instead takes a --refs-file JSON array of {"appId":"...","id":"..."} objects (file, or - for stdin), since it replaces the entire set rather than adding to it.

access-profiles list

Paginates. Rows don’t carry a member count — the list endpoint reports it as 0 for every profile and takes no parameter that would populate it. Use get for a real count.

access-profiles get

Usage:
Unwraps the API’s requestCatalogView.requestCatalog envelope, so the profile’s own keys (id, displayName, published, …) sit at the top level beside the view’s own siblings (memberCount, accessEntitlementsPath, createdByUserPath). A get also returns the profile’s accessEntitlements (its visibility bindings), which list rows leave out.

access-profiles create

Usage:
Only --display-name is required; every other field is omitted from the request unless you pass it, so the server’s own defaults apply. c1i prints the created profile unwrapped like get, so read the ID from .id and the member count from .memberCount. Example:

access-profiles update

Usage:
This is a partial update: only the fields you pass are changed, and the update mask is derived automatically from which flags you supplied — there’s no separate --update-mask flag here. An explicit --description "" is itself a change (it clears the description); an omitted flag is left alone. The updated profile is printed unwrapped, like create.

access-profiles delete

Usage:
The profile is retained for audit: it drops out of list, but get still returns it with deletedAt populated.

access-profiles requestable-entitlements add

Usage:

access-profiles requestable-entitlements remove

Usage:

access-profiles requestable-entitlements set

Usage:
Every existing requestable entitlement not in the array is removed; pass [] to clear the entire set.

access-profiles visibility-entitlements add

Usage:

access-profiles visibility-entitlements remove

Usage:

access-profiles bundle-automation create

Usage:
The supported fields are createTasks, disableCircuitBreaker, and enabled (all booleans), and entitlements (an object with entitlementRefs, an array of {"appId":"...","id":"..."} objects).

access-profiles bundle-automation set

Usage:
Takes the same fields as bundle-automation create.

access-profiles bundle-automation run

Usage:

Access reviews

Manage access-review campaigns — the governance campaigns the API calls access reviews. A campaign defines a scope of users and entitlements to certify, who reviews them, and reports export the campaign’s results. create takes the complete request body as JSON, since campaign scope is a large nested oneof shape; update takes a partial access-review object plus an explicit --update-mask.

access-reviews create

Usage:
The request must contain at least one owner ID in ownerIds.

access-reviews update

Usage:
The command inserts the campaign ID into the body and wraps the request; both flags are required.

access-reviews reports generate

Usage:
The command prints {}, which confirms that generation was requested, not that the report is ready — use reports list to find the report’s state and its time-limited downloadUrl.

Findings

Manage security findings and the public API surfaces that govern them: routing rules, transformation rules, detector settings, and the audit/occurrence search surfaces behind them. create, state, assignee, the bulk commands, routing/transformation-rule management, and settings update all take JSON files so oneof actions and nested rule documents reach the API unchanged. Pass --body-file - to read JSON from standard input. Paginates. A missing --body-file searches all accessible findings.

Role mining

Manage role mining: analyses that cluster users into cohorts sharing similar entitlements, the suggestions those analyses produce, and the access profiles you can generate from a cohort. Mutations and searches take JSON request objects through --body-file so profile filters, entitlement selections, and full configuration documents reach the API unchanged; pass --body-file - to read JSON from standard input. The fixed list commands (suggestions list, runs list, custom-analysis list) return a single, fixed-size page capped only by --limit.

Automations

List C1 automations, inspect, update, or delete one, and query the run history of their executions. executions list is the usual starting point for “did this automation run?” and “why did it fail?”.

automations list

Paginates.

automations update

Update an automation’s display name, description, or enabled state. c1i builds the update mask from the flags you pass, so an explicit --enabled=false or an empty --description is a change, and an omitted flag is left alone. These flags leave the automation’s steps and triggers unchanged. Usage:
To change anything else, such as triggers, steps, or draft fields, pass an automation object with --body-file and name the fields to change in --update-mask. Masking triggers replaces the published triggers and increments currentVersion; isDraft and draftTriggers stay as they were. The updated automation is returned as formatted JSON, unwrapped like automations get. webhookCapabilityUrl and webhookHmacSecret stay top-level fields. Example:

automations delete

Soft-delete an automation. It leaves automations list, but automations get still returns it at exit 0, with no field marking it deleted. Deleting it again exits 0 again. Prints {}; exit 0 means success. Usage:

automations executions list

Paginates. c1i applies --state and --template-id client-side after fetching each page, because the executions endpoint doesn’t support server-side filtering. A narrow filter still scans every page the server returns, so combine it with --limit to bound the work. Example:

Functions

Inspect C1 functions: the serverless TypeScript modules that run in C1’s sandbox and are invoked as automation steps, from the UI, or through the API.

functions list

Paginates.

functions source

Fetch the TypeScript source for a function. Without --commit, c1i resolves the function’s published commit, falling back to its head (latest draft) if nothing is published. The API returns source files base64-encoded; c1i decodes them and prints each file as text, separated by a delimiter line. Usage:
With --out-dir, c1i writes files with mode 0600 and creates the directory (or tightens it, never widens it) to at most 0700, because fetched source can inline credentials.

Export

Export bulk data from C1.

export events

Export C1 system log events, in OCSF format, as an NDJSON stream with one event per line. Redirect the output to a file to archive events or ship them to an external system. Paginates. Examples:

Upgrade

Check for and install a newer c1i release. The command is aliased as update. Usage:
c1i follows a release channel from the C1 distribution center (dist.conductorone.com); see Upgrade c1i. Before it replaces a standalone binary, it verifies the release manifest’s Sigstore signature (signed by the release workflow run for that c1i tag) and the download’s SHA-256 from that manifest. For a Homebrew, go install, or container install, upgrade prints that method’s upgrade command and exits 0 without replacing anything. --check prints one JSON object with these keys: Windows and system installs print a hint but no upgrade_command. With the global --dry-run flag, upgrade fetches and verifies the release (index, manifest, signature, and TUF root) and checks that the install directory is writable. It prints one JSON object on stdout: dryRun, requests for the download it would make ([] when no download is needed), and an upgrade object with the --check fields; for a standalone update it also includes asset_url, sha256, and destination. It takes no lock, doesn’t prompt, and installs nothing. --fields is a usage error unless you pass --check. upgrade treats the distribution center as a system beyond C1. A distribution center 404, 429, or 5xx exits 4, 5, or 6, and a same-path redirect loop exits 6. Any other 4xx, a refused redirect, a non-JSON 200, or a TUF, signature, or checksum failure exits 8.

Service principals

Manage service principals — tenant-owned non-human identities. The group is aliased as service-principal and sp, and its credentials subgroup as credential and creds. A service principal is an identity; a client credential on it is what a caller authenticates with (a client ID and secret). A binding lets another subject — a function, SSO application, AuthZEN server, or edge — act as the principal. The bindings surface is a draft API and may change. delete and credentials revoke are soft: get and credentials get still return the record at exit 0 with nothing marking it as deleted. users get <sp-id> shows "status": "DELETED" and deletedAt. Only list and credentials list omit deleted records.

service-principals credentials create

Usage:
c1i prints the credential unwrapped, with the secret as a sibling field: read .id, .clientId, and .clientSecret. The secret appears only in this output, so capture it now.

service-principals bindings add

Idempotent; prints {}. Usage:
Exactly one subject must be given, and an app-scoped subject (--sso-application-id, --authzen-server-id, --edge-id) requires its paired --*-app-id flag.
These examples use conductor.one. If your organization is on the EU data residency instance, substitute c1eu.ai in URLs, client IDs, and hostnames.

Webhooks

Manage outbound webhooks: the registered https endpoints that C1 calls, for example from a policy’s webhook approval or provision step. The group is aliased as webhook. A webhook has no signing secret, so create and get return the same fields. webhooks list returns pages larger than --page-size: the server raises a size below 5 to 5 and returns one row more than that, so use --limit for an exact count.

webhooks create and webhooks update

Usage:
The endpoint flag is --destination-url, not --url, which stays the global tenant flag. These cases exit with code 2 before c1i sends anything: a --destination-url that isn’t https, has no host, or uses an IPv6 literal host; a blank --display-name; a --callback-timeout with a sign or decimal (-1h, 1.5h); and an update with no field flag. update sends only the flags you pass. Updating a soft-deleted webhook exits 0 and changes it, and it stays deleted. Both commands print the webhook as formatted JSON, unwrapped like webhooks get, so its ID is .id. Example:

webhooks test

Queue a test delivery to a webhook’s URL. Usage:
The delivery is asynchronous. The command prints the queued delivery with "state": "WEBHOOK_STATE_PENDING" and exits 0 whether or not the endpoint is reachable, so exit 0 doesn’t mean the endpoint answered. In the output, .id is the delivery and .webhookId is the webhook you tested.

webhooks delete

Soft-delete a webhook. It leaves webhooks list, but webhooks get still returns it at exit 0 with deletedAt set. Deleting it again exits 0 again. Prints {}; exit 0 means success. Usage:

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. The gateway accepts your stored c1i credentials, so no extra setup is needed.

mcp gateway 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). A gateway cursor that never ends exits with code 8.

mcp gateway call

Invoke a tool exposed by the gateway and print its raw MCP result. Usage:
Find tool names and their input schemas with c1i mcp gateway list-tools --full. call rejects the global --dry-run flag.

MCP servers

Register, configure, and inspect the MCP servers under a C1 app. C1 models an MCP server as a connector under an app, so you address one with --app-id plus its connector ID. Hosted servers run inside C1 from a catalog entry; external servers point at a third-party MCP URL. C1 seals auth secrets server-side, so reads only return *_configured booleans. After you register a server, its tools start in the pending-review state. Approve them with c1i mcp tools approve before the gateway proxies calls to them.

mcp servers get

An MCP server has no id field: its identity is connectorId, the value this command takes as its argument and that mcp servers list rows emit as connector_id. Usage:
Search the MCP servers under one app. The server computes a tool count only when you set --tool-state, so without it c1i omits tool_count from each row instead of showing a 0 that looks like a server with no tools. Paginates. Usage:

mcp servers register

For a hosted server, browse catalog list and pass an entry’s ID with --catalog-id. For an external server, pass --server-url. Usage:
A list read immediately after registering can omit the server for a second or two while mcp servers get already returns it; --wait handles that lag. A timeout exits 1, though the registration was accepted. An explicit --user-id is looked up before sending; an unknown user exits with code 4, including under --dry-run. The per-user token-sharing mode works only with OAuth2 (authorization-code or passthrough), bearer-token, custom-header, and basic-auth methods. register requires --app-id; registering under a new managed app isn’t reachable over REST. Examples:

mcp servers update

c1i derives the update mask from the flags you set, so --display-name alone changes only the name. Auth config and URL aren’t updatable here; use update-credentials. Usage:

mcp servers update-credentials

Replace the auth config, extra config fields, or both on an existing MCP server. It uses the same convenience auth flags and --*-config-file flags as register, and re-seals secrets server-side. Usage:
The mask uses the auth oneof case name (bearerToken, customHeader, basicAuth, oauth2, or none), not the hostedConfig or externalConfig wrapper.

mcp servers delete

This stops the connector, removes it from the tenant’s MCP catalog, and revokes any per-user OAuth credentials issued against it. The connector record is retained for audit. Usage:
Deleting a server cascades: every toolset bound to the connector, and each toolset’s app entitlement, is soft-deleted with it, which affects anyone whose access came through those entitlements. Check what depends on the server first with c1i mcp toolsets list --app-id <app-id> --connector-id <connector-id> and c1i grants list --app-id <app-id> --entitlement-id <entitlement-id>.

mcp servers resync-tools

Re-run tool discovery against an external MCP server using your own credential. Newly discovered tools land in the pending-review state; approve them with c1i mcp tools approve. Hosted servers return resync is only supported for external MCP servers. Usage:

mcp servers test-connection

Probe whether an external MCP server is reachable with the credentials you supply. Outputs formatted JSON with reachable (whether the MCP initialize and tools/list calls both succeeded), toolCount, and a sanitized failureReason. Hosted servers return test connection is only supported for external MCP servers. When the server is unreachable, c1i still prints the JSON, then exits with code 8 and says MCP server is unreachable on stderr, so check the exit code and not just reachable. The command has two modes. In create mode, supply the config to probe with --server-url and optional auth flags, or with --external-config-file. In edit mode, pass a connector ID with --app-id to probe an existing server, naming any changed fields in --update-mask; omit the mask to probe the stored config. Usage:

mcp servers discover-oidc

Fetch the OpenID Connect discovery document for an issuer and return its authorization endpoint, token endpoint, supported scopes, and PKCE methods. Use it to fill in the OAuth2 fields of a register or update-credentials request. Usage:

mcp servers catalog list

Rows include service_name, base_url, default_tool_prefix, stable, and required_scope_count and optional_scope_count, which tell near-duplicate entries apart. Many services appear twice: once as a thin wrapper over the vendor’s REST API, and once as the vendor’s own hosted MCP endpoint, whose service_name typically ends in -mcp. Paginates.

MCP tools

Manage the MCP tools that C1 discovers from a registered server. Newly discovered tools land in the pending-review state, and an admin approves them before the MCP gateway proxies calls to them. Every command requires --app-id and --connector-id to identify the server. Paginates. Usage:

mcp tools approve

Approve MCP tools by setting each tool’s state to approved, which lets the MCP gateway proxy calls to them. Pass one or more tool IDs. The API has no batch approve, so c1i sends each ID as its own request and prints one compact JSON line for each applied tool, with its .id and .state. If one fails, c1i still attempts the rest and exits non-zero with the first failure’s code, while the IDs before it stay approved. A failed write to stdout stops the batch with exit code 1. With --error-format json, each failed ID gets its own error object, and a summary lists the IDs c1i never sent in notAttempted. Usage:
Example:

mcp tools delete

The tool stays in the database for audit but is hidden from listings and unbound from any toolsets. Tools move to the removed state on their own during sync when they disappear from the upstream server; to block a tool without deleting it, use c1i mcp tools approve --state disabled. Usage:

mcp tools history

Outputs NDJSON, one record per historical version. Each record carries the full tool snapshot at that point and the change-history envelope (actor, change kind, creation time, trace ID, system log event ID, and annotations). Paginates; --page-size accepts up to 200. Usage:

MCP toolsets

Manage MCP toolsets: admin-curated groupings of tools, each bound to a single app entitlement so users can request and receive the whole bundle at once. Every command except get-by-entitlement and requestable-connectors requires --app-id and --connector-id to identify the server; get-by-entitlement requires only --app-id.

mcp toolsets get-by-entitlement

Look up the toolset that owns a given app entitlement. Each toolset creates one app entitlement at sync time, so this reverse lookup finds which toolset an entitlement ID from an access-request task represents. Usage:

mcp toolsets create

Create an MCP toolset (access profile) under a connector. After creating it, attach tools with c1i mcp bindings create. Usage:

mcp toolsets update

c1i derives the update mask from the flags you set. Editing the app entitlement behind the toolset isn’t supported here. Usage:

MCP bindings

Inspect and manage bindings between MCP tools and MCP toolsets (access profiles): which tools are members of which toolset. This is a different object from an entitlement proxy binding (entitlement to entitlement), which you manage with c1i entitlements proxy-bindings. Every command requires --app-id and --connector-id to identify the server.

mcp bindings by-tools

Reverse lookup: given a batch of MCP tool IDs, emit one NDJSON record per tool with the toolsets it’s bound to. Tools with no bindings are still emitted, with an empty toolsets array. Usage:

mcp bindings create

Usage:

mcp bindings delete

The tool IDs travel in the request body, so c1i uses the tool_bindings/delete action route rather than an HTTP DELETE. Usage:

mcp bindings history

Stream the binding-change history for either all tools bound to one toolset (--toolset-id) or all toolsets that contain one tool (--tool-id). Pass exactly one of the two. Outputs NDJSON, newest first. Each record carries a list_history metadata envelope plus the items added or removed in that transaction. Paginates; --page-size accepts up to 200. Usage:

MCP classifiers

Manage the AI-governance classifier surfaces used with the MCP gateway (formerly called guardrails in c1i’s user-facing CLI). A classifier is a reusable, ordered rule cascade evaluated first-match-wins. Bind a classifier to an enforcement surface with bindings create; rules may reference tool gates. Templates instantiate curated classifiers (and their dependent gates) into a tenant-owned, editable classifier. The singleton policy surface — the tenant’s one agent classifier policy — is separate from named classifiers. create and update take JSON objects through --body-file (or - for stdin), preserving nested CEL rules, hooks, gates, and template parameters without a lossy flag translation. Updates require an explicit --update-mask as a safeguard — including rules in the mask replaces the entire ordered cascade.

mcp classifiers create

Usage:
displayName is required. Rules are evaluated in listed order, first match wins; leave a new rule’s id empty for the server to assign it.

mcp classifiers update

Usage:
The server requires displayName even when it’s not in the mask. The positional ID overrides any id in the file. Including rules in the mask replaces every rule in evaluation order — read and preserve the existing classifier first if you’re only changing some rules.

mcp classifiers bindings create

Usage:
surface and classifierId are required; targetId identifies the applicable agent or gateway target when the selected surface uses one.

mcp classifiers templates instantiate

Usage:
Required params are declared by templates get and validated by the server.

mcp classifiers templates add-rule

Usage:
ruleIndex defaults to 0; an insertIndex at or past the end of the cascade appends the rule.

mcp classifiers policy update

Usage:
The policy is implicitly created by its first update. Including rules in the mask replaces the entire first-match-wins cascade with the order supplied.

mcp classifiers tool-gates create

Usage:
displayName and grantPolicyId are required. filter may set a CEL expression or a built-in pattern, but never both — the server resolves a built-in pattern to its own CEL expression.

mcp classifiers tool-gates update

Usage:

API

Make raw C1 API requests. This is an escape hatch for accessing any API endpoint not covered by the built-in commands. Usage:
Examples:
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.
c1i sends --body to the API verbatim — it does not wrap or reshape the payload. If the endpoint’s schema nests fields under a top-level key (for example, POST /api/v1/iam/personal_clients/{id} expects {"client": {"displayName": "...", "scopedRoles": ["..."]}, "updateMask": "displayName,scopedRoles"}), your --body must include that wrapper. Use c1i docs endpoint <path> to see the exact request shape before calling.

Pagination and limits

Commands marked “Paginates” (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. Each of those commands takes three flags that control how much data flows: Examples:
A blank --page-token (empty, whitespace-only, or invisible-only) exits with code 2. Without that check, an unset shell variable would turn off auto-pagination and return only the first page. If a server’s pagination cursor stops advancing, c1i doesn’t loop forever. A cursor counts as stuck when nextPageToken repeats, when two or more pages in a row (25 or more rows in all) hold only rows c1i has already seen, or after 100 empty pages in a row. c1i keeps the rows it already printed, warns on stderr that results are INCOMPLETE, and exits with code 6. A list page that is HTML, an array, empty, or truncated also exits with code 6. 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. 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:
Examples:
For shell-specific install steps, run c1i completion <shell> --help.