What is c1i?
c1i (pronounced “see-one-eye”) is a command-line interface for the C1 API, built for automation. Its output is machine-readable and its behavior predictable, so scripts and agents can depend on it:- Structured output: list and search commands return NDJSON (one JSON object per line), and single-object commands return JSON.
- Self-documenting API: the
docscommands search C1 documentation and API schemas without credentials. - Predictable pagination: list commands fetch every page by default.
--page-tokengives you manual control, and--limitcaps the number of results. - Raw API access: the
apicommand calls any C1 API endpoint directly, with optional pagination.
Compare c1i and Cone
C1 provides two CLIs. Use Cone when you work at the terminal interactively, and c1i when you build automation, write scripts, or connect C1 to an AI agent.
See Install Cone to set up Cone.
Install c1i
Download signed macOS, Linux, and Windows binaries, with checksums, provenance, and SBOM attestations, from the C1 distribution center, or install c1i with a package manager:Upgrade c1i
Runc1i upgrade (alias c1i update) to install a newer release from the C1 distribution center. c1i asks for confirmation first; pass -y to skip the prompt, which is required when stdin is not a terminal.
--check reports current, latest, channel, update_available, and install_method. --channel selects stable (the default), latest, or preview.
Before replacing a standalone binary, c1i verifies the release manifest’s Sigstore signature and the download’s SHA-256. For a Homebrew, go install, or container install, c1i upgrade prints that method’s upgrade command and exits without replacing anything.
These examples use
conductor.one. If your organization is on the EU data residency instance, substitute c1eu.ai in URLs, client IDs, and hostnames.Configure your C1 URL
c1i needs your C1 tenant URL. It checks these sources in order and uses the first one that’s set:- The
--urlflag:--url https://example.conductor.one - The
C1I_URLenvironment variable:C1I_URL=https://example.conductor.one - The
urlkey in~/.c1i.yaml:
https://, such as example.conductor.one. c1i requires HTTPS and rejects a bare tenant name such as example.
Authenticate with your browser
Log in through your browser to create a credential for c1i:1
Run
c1i auth login. If no URL is configured, c1i prompts for one, or you can pass it. The first time you log in from a terminal, c1i also asks whether to keep all of your roles; press Enter to keep them. See Limit the credential to specific roles.2
Open the authorization page. c1i opens it in your browser on macOS and Linux; otherwise, open the URL c1i prints in your terminal.
3
Confirm that the code on the page matches the one in your terminal, then click Authorize.
~/.c1i.yaml, c1i then offers to save it there; press Enter to accept. Without a terminal and with no URL configured, c1i auth login exits with an error. See Credential storage for where c1i keeps credentials on each platform.
Limit the credential to specific roles
By default, browser login creates a credential with all of your roles. To give c1i less access, such as only the Basic User role, scope the credential when you log in:- A terminal login with no stored credential asks whether to keep all of your roles or choose; press Enter to keep them all, or pass
--choose-roles=falseto skip the question. - A scoped credential keeps only the overlap between its roles and your own access, so c1i offers the roles you hold, Basic User, and Read-Only Administrator. Super Administrators and Read-Only Administrators see every role.
--scoped-roletakes a role name, such asbasic-user,Basic User, orsystem:user, or a role ID fromc1i roles list. A name that matches no role you can scope to exits with code 2 before your credential is created, and an unknown ID exits with code 4.- c1i checks the new credential with C1 before storing it, and deletes it if C1 scoped it differently or its roles give it no access. To read the role list, c1i briefly creates a temporary credential and deletes it before creating yours.
Authenticate with an existing API credential
To use a client ID and secret you already have, such as a service principal’s credential, store it instead of logging in through the browser:Check and manage your credentials
Use these commands to inspect or remove the credential c1i is using:c1i auth whoami --fields tenant to confirm which tenant it targets. c1i auth logout doesn’t affect credentials set with C1I_CLIENT_ID and C1I_CLIENT_SECRET, which still take precedence.
Credential storage
c1i reads credentials from the first source that has them, in this order:- Environment variables: set
C1I_CLIENT_IDandC1I_CLIENT_SECRET, along withC1I_URL, for scripts, CI runners, and containers. Set both: if only one is set, c1i exits with code 2, except forauth loginandauth logout, which still run and warn on stderr. c1i doesn’t store these credentials. - OS keyring: Keychain on macOS, Credential Manager on Windows, and Secret Service (such as gnome-keyring or KeePassXC) on Linux. c1i uses it whenever one is available.
- File fallback: a
0600file under your config directory:~/.config/c1i/credentials/on Linux,~/Library/Application Support/c1i/credentials/on macOS, and%AppData%\c1i\credentials\on Windows. c1i uses it when no OS keyring is available, which is typical on headless Linux servers, containers, CI runners, and WSL without a desktop environment.
c1i auth login writes to the OS keyring when it can and falls back to the file. c1i auth status reports which source supplied the active credentials.
To avoid minting a new access token for every command, c1i caches it in the OS keyring, or in a 0600 file under tokens/ in your config directory on Unix-like hosts without a keyring. On those hosts, each write to the file cache deletes expired or unusable token files left in that folder. c1i auth token always mints a fresh token. Set C1I_NO_TOKEN_CACHE=1 to turn the cache off.
Explore the API without credentials
Thedocs commands work without authentication, so you can explore the C1 API before you log in:
Uninstall c1i
Removing the c1i binary leaves its configuration, credentials, and caches behind. c1i can’t list keyring entries or keep track of the tenants you’ve logged in to, so log out of each tenant before you remove the binary. To uninstall c1i completely:1
Unset
C1I_CLIENT_ID and C1I_CLIENT_SECRET if both are set, including in any shell profile that exports them. Otherwise logout still removes the stored credentials, but drops the cached token for the environment-variable credentials instead of the token for the stored credentials.2
Run
c1i auth logout once for each tenant you’ve logged in to. Logout removes the stored credentials and their cached token. A token cached under credentials you have since replaced stays in the keyring.3
Remove the c1i binary using the same method you installed it with.
4
Delete the files c1i leaves behind:
~/.c1i/: the OpenAPI spec cache.~/.c1i.yaml: the config file.c1i/in your config directory: the file-fallback credentials (credentials/) and the access-token file cache (tokens/). See Credential storage for each OS’s config directory.- Any shell completion script you installed, such as
~/.local/share/bash-completion/completions/c1i, and thec1i completion powershellline in your PowerShell profile. See Completion.
~/.sigstore/root/ in place. c1i upgrade uses it to verify releases, and other Sigstore tools share it.5
Optional. Remove leftover keyring entries by hand. c1i stores credentials under On Windows, open Credential Manager > Windows Credentials and remove
c1i/<host> and cached access tokens, including tokens for environment-variable credentials, under com.conductorone.c1i.tokens. Older releases stored a <name>.conductor.one tenant’s credentials under c1i/<name>. Replace <host> with a tenant’s host, such as example.conductor.one, or with <name> for an entry an older release stored:c1i/<host>:client_id, c1i/<host>:client_secret, and every com.conductorone.c1i.tokens: entry. To find which hosts you have, search for c1i in Keychain Access on macOS, Seahorse on Linux, or Credential Manager on Windows.Output conventions
c1i output is built for programs to parse:- List and search commands, such as
users listandapps list, output NDJSON: one JSON object per line. - Single-object commands, such as
users getandauth whoami, output formatted JSON. - Commands that change something, such as
apps createandtasks approve, print the API’s response as formatted JSON, unwrapped the same way the matchinggetcommand unwraps it. Read an ID withjq -er .id; the ID path differs for a few commands, such as.connectorIdfor an MCP server. Deletes and other empty responses print{}, and exit code0means success.--fieldsisn’t allowed on these commands. auth login,auth status, andauth logoutprint plain text.- The
apicommand outputs formatted JSON, or NDJSON when you add--paginate. - The
docscommands vary by subcommand: NDJSON forsearchandendpoints, Markdown forpage,readme, andchangelog, JSON forendpoint, and YAML foropenapi.
--page-token. To cap the number of results, pass --limit; c1i requests only as many results as it needs.
With --error-format json, every line c1i writes to stderr is one JSON object (NDJSON). --dry-run prints one JSON object that previews the requests, with credentials redacted. See Errors and exit codes and Dry run in the command reference.
See the c1i command reference for every command, subcommand, and flag.