Skip to main content
Install c1i, point it at your tenant, and log in once; every command after that uses the stored credential.

​
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 docs commands search C1 documentation and API schemas without credentials.
  • Predictable pagination: list commands fetch every page by default. --page-token gives you manual control, and --limit caps the number of results.
  • Raw API access: the api command 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.
If you use an AI coding agent, run c1i docs agents to generate a skill file that teaches it how to use c1i. See Use c1i with AI agents for setup steps for Claude Code, Cursor, and other agents.

​
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

Run c1i 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:
  1. The --url flag: --url https://example.conductor.one
  2. The C1I_URL environment variable: C1I_URL=https://example.conductor.one
  3. The url key in ~/.c1i.yaml:
Pass the full host, with or without 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 stores the new credential for your tenant. In an interactive terminal, if the URL didn’t come from ~/.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=false to 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-role takes a role name, such as basic-user, Basic User, or system:user, or a role ID from c1i 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.
The credential appears in C1 as “Created by c1i (Basic User)”, and c1i prints its scope. Commands its roles don’t cover fail with a permission error.

​
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:
c1i checks the credential with C1 and keeps it only if it works.

​
Check and manage your credentials

Use these commands to inspect or remove the credential c1i is using:
Before a script makes changes, run 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:
  1. Environment variables: set C1I_CLIENT_ID and C1I_CLIENT_SECRET, along with C1I_URL, for scripts, CI runners, and containers. Set both; c1i ignores one without the other. c1i doesn’t store these credentials.
  2. 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.
  3. File fallback: a 0600 file 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. c1i auth token always mints a fresh token. Set C1I_NO_TOKEN_CACHE=1 to turn the cache off.

​
Explore the API without credentials

The docs commands work without authentication, so you can explore the C1 API before you log in:

​
Output conventions

c1i output is built for programs to parse:
  • List and search commands, such as users list and apps list, output NDJSON: one JSON object per line.
  • Single-object commands, such as users get and auth whoami, output formatted JSON.
  • auth login, auth status, and auth logout print plain text.
  • The api command outputs formatted JSON, or NDJSON when you add --paginate.
  • The docs commands vary by subcommand: NDJSON for search and endpoints, Markdown for page, JSON for endpoint, and YAML for openapi.
List commands fetch every page by default. To page manually, pass --page-token. To cap the number of results, pass --limit; c1i requests only as many results as it needs. See the c1i command reference for every command, subcommand, and flag.