CLI

The CoderFlow CLI connects your local terminal to the CoderFlow server. Use it to authenticate, start tasks or interactive containers, run ephemeral tests, attach to running containers, and apply completed task patches to local repositories.

Most task creation and review still works best in the Web UI. The CLI is useful for scripted workflows, local patch application, testing from a working tree, and terminal-first development.

Installation

Install the user CLI:

npm install -g @profoundlogic/coderflow-cli

Self-hosting commands use the server package and the coder-server binary:

npm install -g @profoundlogic/coderflow-server

Connect to a Server

Set the server URL, then log in:

coder config set server https://coderflow.example.com
coder login

coder login prompts for a username and password and stores the returned API key. If the server has OIDC SSO enabled, use the device flow:

coder login --sso

The SSO flow checks whether OIDC is enabled, shows a user code, opens the verification URL in your browser when possible, polls for approval, and stores the API key after authentication completes.

Profiles and Configuration

Profiles let you keep separate CLI settings for different CoderFlow servers or environments.

# Create and switch to a profile
coder profile create production --server=https://coderflow.example.com
coder profile switch production

# Add or inspect profile settings
coder profile set default_environment webapp
coder profile get server
coder profile show production

# Use a profile for one command
coder --profile=production list

Profile commands:

Command	Use
coder profile list	List profiles and mark the active one.
coder profile show [name]	Show a profile, or the active profile when no name is provided.
coder profile create <name>	Create a profile. You can pass initial values such as --server=....
coder profile switch <name>	Set the active profile.
coder profile delete <name>	Delete a profile.
coder profile copy <source> <dest>	Copy an existing profile.
coder profile set <key> <value>	Set a value in the active profile.
coder profile get <key>	Print a value from the active profile.
coder profile current	Print the active profile name.

Profile keys are server, apiKey, default_environment, coder_setup_path, server_port, and profound_coder_path.

coder config manages the legacy client config at ~/.coder/config.json. It is still supported, but active profiles override legacy values. Environment variables have the highest priority:

Environment variable	Use
CODER_SERVER_URL	Server URL override.
CODER_API_KEY	API key override.
CODER_PROFILE	Active profile override.

Command Reference

Use this table when you need the command shape quickly. The sections below add workflow details and caveats.

Command	Purpose	Key options and notes
coder login	Authenticate with the server.	--sso starts the OIDC device flow.
`coder config <set	get	remove
coder profile <command>	Manage profile-based settings.	list, show, create, switch, delete, copy, set, get, current.
coder run [task-type]	Create a task.	--environment=<name>, template --param=value, --env=KEY=VALUE, --branch=repo=branch, --jira=KEY, --with-local-state.
coder start [environment]	Start an interactive agent container.	--agent=<agent>, --no-attach, --env=KEY=VALUE, --branch=repo=branch, --with-local-state.
coder shell [environment]	Start an interactive shell container.	Same container options as coder start, but starts in shell mode.
coder attach [container-id]	Attach to a running container.	--shell, --agent=claude, --agent=codex.
coder test [name]	Run an ephemeral test container.	--env=<environment>, --environment=<environment>, --list, --cmd="...", --no-local-state.
coder list	List recent tasks.	Current coder list does not accept filters from the CLI entrypoint.
coder status <task-id>	Show task status.	No additional options.
coder results <task-id>	Show completed task results.	No additional options.
coder logs <task-id>	Show task logs.	--tail=N.
coder reject <task-id>	Reject task results.	--cleanup also removes task artifacts.
coder apply [task-id] [file-path]	Apply completed task patches locally.	Omitting task-id opens interactive task selection. The optional file path limits the applied patch.
coder discard	Discard local uncommitted repo changes.	--env=<environment>, --yes.
coder containers	List CoderFlow containers.	No additional options.
coder containers clean	Delete matching containers.	--stopped, --older-than=Nd, --dry-run, --yes.
coder-server <command>	Manage a self-hosted server.	init, start, stop, status, logs, restart, build, license, config, and admin utilities.

Create Tasks

Use coder run when you need to launch a task from a script or from a terminal-only environment.

# Create a task interactively or with server defaults
coder run

# Run a task template with parameters
coder run add-function --function_name=multiply

# Select an environment
coder run fix-test --environment=webapp

# Link the task to a Jira issue
coder run bugfix --jira=PROJ-123

coder run options:

Option	Use
--environment=<name>	Select the CoderFlow environment.
--<param>=<value>	Pass a task-template parameter.
--env=KEY=VALUE	Add a container environment variable. Repeat for multiple variables.
--branch=repo=branch	Override the branch for a repository in the environment. Repeat for multiple repos.
--jira=ISSUE-KEY	Create the task from a Jira issue key.
--with-local-state	Capture local repository state before the task starts.

For branch overrides, use the repository name from the environment configuration:

coder run bugfix --environment=webapp --branch=api=release/2026-05 --branch=ui=feature/nav

The space-separated form also works:

coder run bugfix --branch api=release/2026-05

The server validates branch overrides against the environment. For coder run and coder start, branch overrides for repositories that do not allow branch selection are rejected; omit those repositories and let the container use their configured branch.

Local State

--with-local-state on coder run captures repository state from the command's current working path and applies it inside the task container. Run it from a repository or from a parent directory that contains the environment's repositories.

Captured state includes:

• The current branch and commit
• Local-only commits when a base branch can be found
• Staged and unstaged changes
• Untracked text files up to 1 MB each

Very large patches are rejected before task launch. Repositories that cannot be found use the normal container checkout.

Interactive Sessions

Use coder start to launch an interactive container and connect to the configured agent.

# Start and attach to the default agent
coder start webapp

# Start with a specific agent
coder start webapp --agent=codex

# Start the container but attach later
coder start webapp --no-attach

# Pass environment variables and branch overrides
coder start webapp --env=NODE_ENV=test --branch=api=feature/search

coder shell is shorthand for starting an interactive session in shell mode:

coder shell webapp

coder start and coder shell options:

Option	Use
--environment=<name>	Select the CoderFlow environment when not using the positional environment argument.
--agent=<agent>	Override the environment's default agent. Common values are claude, codex, gemini, bob, and grok.
--no-attach	Start the container without opening a terminal connection.
--env=KEY=VALUE	Add a container environment variable. Repeat for multiple variables.
--branch=repo=branch	Override the branch for a repository. Repeat for multiple repos.
--with-local-state	Capture local repository state before the container starts.

After a container starts, the CLI remembers its ID so coder attach can reconnect later.

Attach to Containers

Attach connects your local terminal to an existing running container.

# Reconnect to the last container started by the CLI
coder attach

# Attach to a specific container
coder attach <container-id>

# Open bash instead of resuming the agent
coder attach --shell

# Resume with a specific supported agent
coder attach --agent=codex

Without --shell, the CLI resumes the container's default agent. --agent=claude and --agent=codex have explicit resume commands; other container default agents are started by name.

Run Tests

coder test runs an ephemeral test container and streams the test output back to your terminal.

# Run a named test from the environment's test definitions
coder test unit --env=webapp

# List available tests
coder test --list --env=webapp

# Run a one-off command
coder test --cmd="npm test" --env=webapp

# Use the default environment and skip local state
coder test unit --no-local-state

coder test options:

Option	Use
--env=<environment> or --environment=<environment>	Select the environment.
--list	List tests defined for the environment.
--cmd="<command>"	Run a custom command instead of a named test.
--no-local-state	Skip local repository state capture.

Unlike coder run and coder start, tests capture local state by default. The CLI reads the environment's repositories, captures matching local repos from your current working directory, sends that state to the server, starts the test container, streams logs, and exits with the test container's exit code.

Named tests can limit state capture to specific repositories. A test definition with an empty repos array skips local state for that test.

Review Task Results

Use these commands when you prefer terminal output over the task page.

# List recent tasks
coder list

# Check one task
coder status <task-id>

# Show completed task details, summary, and changed files
coder results <task-id>

# Show logs
coder logs <task-id>
coder logs <task-id> --tail=100

# Reject results
coder reject <task-id>
coder reject <task-id> --cleanup

Current coder list does not accept --status or --environment filters from the CLI entrypoint. Use the Web UI for filtered task lists until those options are wired through.

coder reject --cleanup also asks the server to remove task artifacts.

Apply or Discard Local Changes

coder apply applies patches from a completed task to local repositories.

# Pick from recent completed tasks
coder apply

# Apply a specific task
coder apply <task-id>

# Apply only one file path from that task's patch
coder apply <task-id> src/app.js

Run coder apply from the parent directory that contains the repositories, or from a directory where each repository path matches the environment configuration. The command writes the patch to your working tree; it does not commit the changes. Review with git status, then stage and commit normally.

Use coder discard to undo uncommitted local changes in repositories for an environment:

coder discard
coder discard --env=webapp
coder discard --yes

coder discard checks each configured repository, runs the equivalent of unstage, restore, and clean operations, and removes untracked files. Use it only when you intend to discard local work.

Container Management

Use coder containers to inspect and clean CoderFlow containers through the server API.

# List containers
coder containers

# Remove stopped containers without prompting
coder containers clean --stopped --yes

# Preview containers older than 7 days
coder containers clean --older-than=7d --dry-run

Cleanup options:

Option	Use
--stopped	Only clean stopped containers.
--older-than=Nd	Only clean containers older than the specified number of days, such as 7d or 30d.
--dry-run	Show matching containers without deleting them.
--yes or -y	Skip the confirmation prompt.

Server Administration CLI

Self-hosting and license management use coder-server, not the user coder command.

# Create a setup repository
coder-server init mycompany-coder-setup

# Start and manage the server
coder-server start --setup-path=/path/to/coder-setup
coder-server start --setup-path=/path/to/coder-setup --daemon
coder-server status
coder-server logs --tail=100
coder-server logs --follow
coder-server stop
coder-server restart

# Manage the license
coder-server license set <license-key>
coder-server license show
coder-server license verify

coder-server start also accepts --port=<port>. Server-side configuration, including coder_setup_path, server_port, SSL certificate paths, and selected setup values, is managed with coder-server config.

Option Notes

Some option names are command-specific:

• Use --environment=<name> for coder run, coder start, and coder shell.
• Use --env=<environment> for coder test and coder discard.
• Use --env=KEY=VALUE for container environment variables on coder run, coder start, and coder shell.
• Use the repo-qualified branch form, --branch=repo=branch, for multi-repo environments.
• Use --profile=<name> before the command to override the active profile for a single command.

Getting Help

coder --help
coder --help-all
coder <command> --help
coder-server --help