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 export <task-id>	Download a portable task package.	--output=<file.zip>, -o <file.zip>, --workspace=delta|full|none.
coder import <directory-or-zip>	Create an objective or task from a package or workspace directory.	--mode=objective|staged|running, --environment=<name>, --name=<name>, --agent=<agent>, --instructions=<text>, --require-matching-base.
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, grok, and kimi.
--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.

Export and Import Tasks

coder export downloads a task as a portable ZIP package, and coder import recreates it - on the same server or a different one. See Export and Import Tasks for what the package contains and when to use each import mode.

# Download the package using the server's filename
coder export 1759542727986-3uoyf48lr

# Choose the destination file
coder export 1759542727986-3uoyf48lr --output ./task-backup.zip

# Carry the entire /workspace instead of just the task's changes
coder export 1759542727986-3uoyf48lr --workspace=full

By default the package carries only the files the task added, modified, or deleted, and importing it merges them into the destination environment's own initialized workspace.

Import an export package, or a plain local workspace directory that CoderFlow packages for you before uploading:

# Restore a ready-to-use staged container (the default)
coder import ./task-backup.zip

# Package a local directory and restore it into an environment
coder import ./my-workspace --environment=myproject

# Store the package as a reusable objective
coder import ./task-backup.zip --mode=objective

# Restore and start the agent immediately
coder import ./task-backup.zip --mode=running --agent=codex

coder import options:

Option	Use
--mode=<mode>	objective, staged (default), or running.
--environment=<name>	Destination environment. Worth naming for a plain workspace directory, which carries no package metadata to select one.
--name=<name>	Override the imported task name.
--agent=<agent>	Override the agent recorded in the package.
--instructions=<text>	Override the instructions used when the task runs.
--require-matching-base	Refuse a workspace delta whose repositories were exported from a different base commit, remote, or branch. Without it the mismatch is reported and the delta is applied anyway. The check runs after the import is accepted, so a refusal appears as a failed task rather than a failed command.

Without --environment, CoderFlow uses the environment named in the package, falling back to your default environment and then to the server default. The import fails if the environment that resolves does not exist on this server, or if you lack permission to create tasks in it.

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 license seats
coder-server license deactivate [uuid]

coder-server license seats lists the seats currently in use for your license, including the user data attached to each seat (see Attaching Data to a Seat). coder-server license deactivate frees a seat, defaulting to this host's own seat when no UUID is given.

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