Codi command reference

Codi uses singular resources and consistent verbs:

codi [global-options] <resource> <verb> [identifier] [options]

Options may appear before or after positional arguments. Use codi help, codi help <resource>, or codi <resource> <verb> --help to read contextual help from the installed client.

Global options

Option Behavior

Option	Behavior
`--profile <name>`	Use a local profile without changing the active profile.
`--workspace <id\|slug>`	Use a workspace for one command without changing the workspace stored in the profile.
`--output table\|json`	Select human-readable tables or machine-readable JSON. The default is `table`.
`--quiet`	Print identifiers or other minimal values where the command supports it.
`--no-color`	Disable terminal colors.
`--timeout <seconds>`	Override the request timeout with a value from 1 to 300 seconds.
`--help`, `-h`	Show help for the selected command or command group.

--profile <name>

Use a local profile without changing the active profile.

--workspace <id|slug>

Use a workspace for one command without changing the workspace stored in the profile.

--output table|json

Select human-readable tables or machine-readable JSON. The default is table.

--quiet

Print identifiers or other minimal values where the command supports it.

--no-color

Disable terminal colors.

--timeout <seconds>

Override the request timeout with a value from 1 to 300 seconds.

--help, -h

Show help for the selected command or command group.

codi --version is an alias for codi version.

Environment variables

Variable Default Behavior

Variable	Default	Behavior
`CODINAMO_SERVER_URL`	`https://codinamo.com`	Select the server when no stored profile overrides it.
`CODINAMO_ACCESS_TOKEN`	Unset	Authenticate without reading a locally stored profile token. Use this for CI.
`CODINAMO_HTTP_TIMEOUT_SECONDS`	`30`	Set the default request timeout from 1 to 300 seconds.
`CODINAMO_ALLOW_INSECURE_HTTP`	`false`	Allow an `http://` server URL when explicitly set to `true` or `1`. Keep this disabled outside an isolated development environment.

CODINAMO_SERVER_URL

https://codinamo.com

Select the server when no stored profile overrides it.

CODINAMO_ACCESS_TOKEN

Unset

Authenticate without reading a locally stored profile token. Use this for CI.

CODINAMO_HTTP_TIMEOUT_SECONDS

30

Set the default request timeout from 1 to 300 seconds.

CODINAMO_ALLOW_INSECURE_HTTP

false

Allow an http:// server URL when explicitly set to true or 1. Keep this disabled outside an isolated development environment.

Server URLs must contain only a scheme and authority. HTTPS is required unless insecure HTTP is explicitly enabled.

Client, status, authentication, and profiles

codi help
codi help <command-group>
codi version
codi completion <bash|zsh|fish>
codi status [--server <url>]

codi auth login [--email <email>] [--server <url>] [--password-stdin]
codi auth signup [--name <name>] [--email <email>] [--handle <handle>] \
  [--server <url>] [--password-stdin]
codi auth logout
codi auth whoami

codi profile list
codi profile use <name>
codi profile show
codi profile create <name> --server <url>
codi profile delete <name> [--yes]

auth login prompts for a missing email and reads the password without echo. auth signup prompts for missing account fields and password. With --password-stdin, the password is read from standard input.

auth logout removes the credential for the selected profile. profile delete removes the profile, its workspace selection, and its stored credential.

Workspaces, organizations, and teams

codi workspace list
codi workspace create <name> [--slug <slug>]
codi workspace use <id|slug>
codi workspace current
codi workspace rename <id|slug> <name>

codi organization list
codi organization show <organization>
codi organization create <name> [--slug <slug>]
codi organization rename <organization> <name>

codi team list --organization <organization>
codi team show <team> --organization <organization>
codi team create <name> --organization <organization> [--slug <slug>]
codi team rename <team> <name> --organization <organization>
codi team member list <team> --organization <organization>
codi team member add <team> --organization <organization> --email <email>
codi team member remove <team> <member> --organization <organization> [--yes]

Organization selectors accept a canonical ID, unique name, or slug. Team selectors accept a canonical ID, unique name, or slug inside the selected organization. A team member may be selected by user ID, email, handle, or unique name.

Access, roles, and grants

codi access catalog
codi access capabilities [--resource <type:id>]
codi access decision --permission <code> --resource <type:id>

codi role list --organization <organization>
codi role show <role> --organization <organization>
codi role preview --organization <organization> --file <role.json>
codi role create <name> --organization <organization> --file <role.json>
codi role update <role> --organization <organization> --file <role.json>
codi role duplicate <role> <name> --organization <organization> \
  [--description <text>]
codi role delete <role> --organization <organization> [--yes]

codi grant list --organization <organization> [--scope <type:id>]
codi grant create --organization <organization> --file <grant.json>
codi grant update <grant> --organization <organization> --file <grant.json>
codi grant revoke <grant> --organization <organization> [--yes]
codi grant effective --organization <organization> \
  --principal <user|team:id> --resource <type:id>
codi grant principals --organization <organization> [--query <text>]

Resource and principal references use TYPE:ID. Type matching is case-insensitive.

A role definition is a JSON object with permissions and assignableScopeTypes arrays. name, description, and expectedVersion are optional where applicable:

{
  "description": "Can operate project pipelines",
  "permissions": ["pipeline.read", "pipeline.run"],
  "assignableScopeTypes": ["PROJECT"],
  "expectedVersion": 3
}

A grant definition identifies its principal, role, and scope. expiresAt and expectedRevision are optional:

{
  "principalType": "TEAM",
  "principalId": "TEA-123",
  "roleId": "ARO-456",
  "scopeType": "PROJECT",
  "scopeId": "PRO-789",
  "expiresAt": null,
  "expectedRevision": 2
}

Role selectors accept an ID, system code, or unique name. Grant selectors use the canonical grant ID. Pass - to --file to read a role or grant definition from standard input.

Projects, repositories, and actions

codi project list
codi project show <project>
codi project create <name> [--git]
codi project update <project> --name <name>
codi project delete <project> [--yes]

codi repository show <project>
codi repository enable <project>
codi repository tree <project> [--path <path>]

codi action list [--category <category>]
codi action show <action-code>

Project selectors accept a canonical ID or unique name. Actions may be selected by code or unique display name.

Registry

codi registry show <project>
codi registry enable <project>
codi registry update <project> --visibility <private|public>
codi registry repositories <project>
codi registry disable <project> [--yes]
codi registry token list <project>
codi registry token create <project> <name> \
  --permissions <pull[,push]> [--expires-at <instant>]
codi registry token revoke <project> <token> [--yes]

Registry token selectors accept the token ID or unique name. token create returns the secret once; subsequent list operations return metadata only.

Pipelines and runs

codi pipeline list [--project <project>]
codi pipeline show <pipeline>
codi pipeline create <name> --project <project>
codi pipeline validate --file <pipeline.ice>
codi pipeline update <pipeline> --file <pipeline.ice>
codi pipeline export <pipeline> [--file <path>]
codi pipeline run <pipeline> [--follow]
codi pipeline configure <pipeline> --continue-on-error <true|false>
codi pipeline attach-secret-group <pipeline> <secret-group>
codi pipeline detach-secret-group <pipeline>
codi pipeline attach-variable-group <pipeline> <variable-group>
codi pipeline detach-variable-group <pipeline>
codi pipeline delete <pipeline> [--yes]

codi run list [--pipeline <pipeline>]
codi run show <run>
codi run logs <run> [--follow]
codi run reports <run>
codi run cancel <run>

Pipeline, variable-group, and secret-group selectors accept a canonical ID or unique name. Run selectors use the canonical RUN-… ID.

pipeline validate and pipeline update accept --file - to read ICE from standard input. Without --file, pipeline export writes ICE to standard output. With --follow, pipeline execution or log output is polled until the run reaches a terminal state.

Variables and secrets

codi variable-group list
codi variable-group show <group>
codi variable-group create <name> [--description <text>]
codi variable-group set <group> <name>=<value>
codi variable-group unset <group> <name>
codi variable-group delete <group> [--yes]

codi secret-group list
codi secret-group show <group>
codi secret-group create <name> [--description <text>]
codi secret-group set <group> <name> [--stdin]
codi secret-group unset <group> <name>
codi secret-group delete <group> [--yes]

Variable values are part of the positional name=value operand. Secret values are never accepted as operands or options: Codi reads them without echo or from standard input.

Agents and deployment targets

codi agent list
codi agent enrollment-token <name> [--expires-in <seconds>]
codi agent delete <agent> [--yes]

codi target list
codi target show <target>
codi target create <name> --reference <reference-name> --kind <kind> \
  --strategy <strategy> --config <target.json> [--agent <DSA-id>]
codi target update <target> [--name <name>] [--reference <reference-name>] \
  [--kind <kind>] [--strategy <strategy>] [--config <target.json>] \
  [--agent <DSA-id>|--clear-agent]
codi target disable <target>
codi target enable <target>

Agent selectors accept a canonical ID or unique name. Target selectors accept a canonical ID, unique name, or unique reference name.

Target kinds are machine, container, and swarm. Update strategies are docker-compose, docker-container, and docker-swarm. The --config file must contain a JSON object and may be - to read from standard input. target update preserves fields that are not supplied.

Dashboard

codi dashboard show
codi dashboard recent
codi dashboard pipelines

Dashboard commands summarize the active workspace. show returns the complete overview, while recent and pipelines return focused views.

Destructive commands

The following operations request confirmation unless --yes is present:

profile deletion;
team-member removal;
role archival and grant revocation;
project, pipeline, variable-group, secret-group, and agent deletion;
Registry disablement and Registry-token revocation.

When --output json is selected, destructive commands cannot prompt and require --yes.

Output and errors

Table output is intended for people. JSON output returns structured response objects for scripts. Diagnostic errors are written to standard error. In JSON mode, an error has this shape:

{
  "code": "FORBIDDEN",
  "message": "Permission denied",
  "httpStatus": 403
}

Exit code Meaning

Exit code	Meaning
`0`	The command completed successfully.
`1`	The operation did not succeed, including an unavailable status check, invalid pipeline source, or unclassified runtime/API failure.
`2`	The command or local input is invalid.
`3`	The server returned HTTP 401; authentication is missing or no longer valid.
`4`	The server returned HTTP 403, or `access decision` returned denied.
`5`	The server returned HTTP 404.
`6`	The server returned HTTP 409 or 412 because current state, version, or revision conflicts with the request.

0

The command completed successfully.

1

The operation did not succeed, including an unavailable status check, invalid pipeline source, or unclassified runtime/API failure.

2

The command or local input is invalid.

3

The server returned HTTP 401; authentication is missing or no longer valid.

4

The server returned HTTP 403, or access decision returned denied.

5

The server returned HTTP 404.

6

The server returned HTTP 409 or 412 because current state, version, or revision conflicts with the request.

See Work with Codi for task-oriented examples and Troubleshoot Codi for diagnosis.