How it works Docs Prices
Login Sign up
Browse documentation

Work with Codi

codi is the command-line client for Codinamo. It operates the same server-owned resources as the web application, so changes made in either interface are immediately visible in the other.

Commands use a resource-oriented shape:

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

Resources are singular and verbs are consistent. For example:

codi workspace list
codi project create backend --git
codi pipeline update build-deploy --file pipeline.ice
codi run logs RUN-123 --follow

Use contextual help when composing a command:

codi help
codi help registry
codi registry token create --help

See Codi command reference for documented command syntax and global options.

Check the client and server

Display the client version or check whether a Codinamo server is reachable:

codi version
codi status
codi status --server https://codinamo.com

status does not require authentication. It returns a nonzero exit status when the server is unavailable, making it suitable for diagnostics and readiness checks.

Codi can generate completion definitions for Bash, Zsh, and Fish. The following commands enable completion in the current shell session:

source <(codi completion bash)
source <(codi completion zsh)
codi completion fish | source

Run only the line for the active shell.

Configure profiles and authenticate

A profile stores a server URL and the current workspace. Authentication credentials are stored separately with owner-only file permissions.

codi profile create production --server https://codinamo.com
codi profile use production
codi profile show
codi profile list

codi auth login --email user@example.com
codi auth whoami

auth login prompts for a password without echo. To authenticate from a non-interactive environment, read the password from standard input:

printf '%s\n' "$CODINAMO_PASSWORD" \
  | codi auth login --email user@example.com --password-stdin

Create an account interactively with codi auth signup. Name, email, and handle can also be provided as options; the password is still read without echo or through --password-stdin.

Use codi auth logout to remove the stored token for the selected profile. Deleting a profile removes both its local context and its stored credential:

codi auth logout
codi profile delete production

For CI, provide CODINAMO_ACCESS_TOKEN through the runner’s secret mechanism. Do not place access tokens or passwords directly in command arguments.

Select a workspace

Most delivery resources are scoped to an active workspace. Select it once in the profile:

codi workspace list
codi workspace create platform --slug platform
codi workspace use platform
codi workspace current

Use --profile or --workspace to override local state for one command:

codi project list --profile production --workspace platform

A selector may be a canonical ID or a unique name. Organizations and workspaces also accept their slug; deployment targets also accept their reference name. If a name is ambiguous, Codi asks for the canonical ID instead of guessing.

See Resource identifiers for the public ID prefixes.

Manage organizations and teams

Organization commands operate above workspace context. Team commands always identify their organization explicitly:

codi organization list
codi organization create Acme --slug acme
codi organization show acme

codi team create developers --organization acme
codi team member add developers \
  --organization acme --email developer@example.com
codi team member list developers --organization acme

Use team member remove to remove membership. This may change access inherited through the team, but it does not remove grants assigned directly to the user.

See Organizations and namespaces and Teams and membership.

Inspect access

Use the authorization catalog to discover permission and resource codes. Capabilities show every decision for a resource; decision checks one permission and returns exit code 4 when access is denied.

codi access catalog
codi access capabilities --resource WORKSPACE:WKS-123
codi access decision \
  --permission pipeline.run --resource PIPELINE:PIP-456

When access capabilities has no --resource, it inspects the active workspace.

Manage roles and grants

Roles and grants use JSON files so their definitions remain reviewable and do not become long command lines. Preview a role before creating it:

{
  "description": "Can operate project pipelines",
  "permissions": ["pipeline.read", "pipeline.run"],
  "assignableScopeTypes": ["PROJECT"]
}
codi role preview --organization acme --file project-operator.json
codi role create "Project Operator" \
  --organization acme --file project-operator.json
codi role list --organization acme

A grant connects a user or team, a role, and a resource scope:

{
  "principalType": "TEAM",
  "principalId": "TEA-123",
  "roleId": "ARO-456",
  "scopeType": "PROJECT",
  "scopeId": "PRO-789",
  "expiresAt": null
}
codi grant create --organization acme --file grant.json
codi grant list --organization acme --scope PROJECT:PRO-789
codi grant effective --organization acme \
  --principal TEAM:TEA-123 --resource PROJECT:PRO-789

Role creation and update run the server preview before mutation. When a role version or grant revision is omitted, Codi reads the current value and uses it for optimistic concurrency control.

See Manage access and Access catalog.

Discover actions and source

Inspect the action catalog from the terminal before authoring ICE:

codi action list
codi action list --category build
codi action show MAVEN_BUILD

For hosted source, enable a project repository and inspect its tree:

codi repository enable application
codi repository show application
codi repository tree application --path src

See Action catalog and Hosted Git repositories.

Create and run a pipeline

codi project create application --git
codi pipeline create build-deploy --project application
codi pipeline validate --file pipeline.ice
codi pipeline update build-deploy --file pipeline.ice
codi pipeline configure build-deploy --continue-on-error false
codi pipeline run build-deploy --follow

pipeline validate checks the ICE document without replacing the saved graph. pipeline update validates the source and updates both visual and ICE representations with revision control.

Export the current valid ICE or inspect executions separately:

codi pipeline export build-deploy --file pipeline.ice
codi run list --pipeline build-deploy
codi run show RUN-123
codi run logs RUN-123 --follow
codi run reports RUN-123
codi run cancel RUN-123

The dashboard commands provide workspace-level summaries:

codi dashboard show
codi dashboard recent
codi dashboard pipelines

See Pipelines and visual editor and Runs and logs.

Manage variables and secrets

codi variable-group create production
codi variable-group set production REGION=us-east-1
codi pipeline attach-variable-group build-deploy production

codi secret-group create release --description "Release credentials"
printf '%s' "$REGISTRY_PASSWORD" \
  | codi secret-group set release REGISTRY_PASSWORD --stdin
codi pipeline attach-secret-group build-deploy release

Secret values are read without echo or through standard input. They are never accepted as command arguments or included in Codi output. secret-group show reports only names and configuration state.

See Secrets and Variables and action outputs.

Operate Registry resources

Inspect or enable the Registry attached to a project, list its repositories, and create scoped client credentials:

codi registry enable application
codi registry show application
codi registry repositories application
codi registry token create application local-publisher \
  --permissions pull,push

A newly created Registry token is shown once. Capture it in an approved secret store and revoke it when it is no longer required.

See Container Registry and Registry credentials.

Manage agents and deployment targets

Issue an enrollment token for a DinaSync agent, then create a target from a strategy-specific JSON file:

codi agent enrollment-token production-agent --expires-in 900

codi target create production-api \
  --reference production_api \
  --kind machine \
  --strategy docker-compose \
  --config target.json

The target may be created without --agent and assigned later with target update. Valid kinds are machine, container, and swarm; valid strategies are docker-compose, docker-container, and docker-swarm.

{
  "workingDirectory": "/home/codinamo",
  "composeFile": "docker-compose.yml",
  "projectName": "codinamo",
  "service": "codinamo-backend",
  "imageVariable": "CODINAMO_WEBAPP_IMAGE"
}

See Deployment targets and Install DinaSync.

Automate safely

Use --output json for structured output and --quiet when a command supports identifier-only output. --no-color removes terminal color and --timeout sets a request timeout from 1 to 300 seconds.

workspace_id=$(codi workspace current --quiet)
codi pipeline list --workspace "$workspace_id" --output json

Human-readable results go to standard output and diagnostic errors go to standard error. With --output json, errors use a stable object containing code, message, and httpStatus.

Destructive commands prompt before changing state. In non-interactive automation, pass --yes explicitly; it is required when a destructive command also uses --output json.

See Troubleshoot Codi for exit codes and common failures.