Skip to main content

# 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