---
sidebar_position: 1
---

# 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:

```bash
npm install -g @profoundlogic/coderflow-cli
```

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

```bash
npm install -g @profoundlogic/coderflow-server
```

## Connect to a Server

Set the server URL, then log in:

```bash
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:

```bash
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.

```bash
# 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|show>` | Manage legacy client config. | Client keys include `server`, `apiKey`, and `default_environment`. |
| `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.

```bash
# 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:

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

The space-separated form also works:

```bash
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.

```bash
# 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:

```bash
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.

```bash
# 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.

```bash
# 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.

```bash
# 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.

```bash
# 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:

```bash
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.

```bash
# 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.

```bash
# 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

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