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

CoderFlow packages come from Profound Logic's package registry, https://npm.profoundlogic.com/. Point npm at it for the @profoundlogic scope once for your account, then look up the current release:

npm config set @profoundlogic:registry https://npm.profoundlogic.com/
npm view @profoundlogic/coderflow-cli dist-tags

Install the user CLI, replacing <version> with the latest value printed above:

npm install -g @profoundlogic/coderflow-cli@<version>

Self-hosting commands use the server package and the coder-server binary. Install it as the server's service account, with the same scope line; see Install the Server:

npm install -g @profoundlogic/coderflow-server@<version>

Always name the version. Without the scope line, npm installs the last versions published to registry.npmjs.org (0.16.0) instead; a pinned newer version fails with ETARGET, which shows that the scope line is missing. See Pin the version.

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 env create --from-repo <url> --agent <name>	Preview and generate a Draft environment.	--branch, --name, --provider, --starter, --serving-model, --database, --detect-later, --yes, --json.
coder env generate <name>	Preview and fill a pending Draft.	Uses saved repository access; --starter, --serving-model, --database, --yes, --json.
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. --undo-device-changes also undoes the task's file changes on your computer (CoderFlow Link).
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.

Generate an environment Draft

Use the same Generate from repository workflow as the Web UI:

coder env create --from-repo https://github.com/acme/orders.git --branch main --agent codex
coder env create --from-repo https://github.com/acme/orders.git --agent codex --yes --json

The command previews the repository and branch, stack, components and their start commands and ports, serving model, tests, secret names, database, warnings, unresolved items and suggested name. On a TTY, it asks you to confirm before creating. The result gives the Draft name, status, Finish setup step count, secrets and connections to re-provision, and a link to its environment page. Nothing is built or activated, and no credentials are copied.

Option	Meaning
--from-repo <url>	Required HTTPS repository URL, without credentials.
--branch <branch>	Read this branch; otherwise use the repository's default branch.
--name <name>	Override the suggested environment name.
--description <text>	Environment description.
--agent <name>	Required default agent for the new Draft. If omitted, the command refuses; no agent is selected automatically.
--provider <name>	Read through this connected Git provider instead of treating the repository as a plain URL.
--starter <name>	Layer saved organization defaults under the detected settings.
--serving-model <model>	Choose two-process, single-origin or proxy if available for the repository.
--database <choice>	For a repository that uses a database: local for a throwaway database inside each task container, or connection for a connection to an existing database. Omitted, CoderFlow uses local when it can propose one and connection otherwise. local is refused (invalid_database) when the preview's database.recipe isn't proposed. See Database.
--detect-later	Allow a pending Draft when the repository cannot be read or detected (createWhenUndetected). Supply --name if preview fails.
--yes	Skip confirmation. Required when not on a TTY.
--json	Write one JSON result to stdout, including preview and environment URL. With an interactive prompt, preview JSON also goes to stderr before confirmation.

Values accept both --option value and --option=value. The command uses your active profile and coder login credentials. Server refusals print a fixed code and message and exit nonzero, for example draft_not_permitted, environment_exists or repository_not_accessible. JSON refusals contain code and error. A network failure after submitting creation has an unknown outcome: inspect the Environments page before running the command again.

A PAT is never a command option and must not be embedded in the URL. For a URL that needs one:

coder env create --from-repo https://git.example.com/team/orders.git --name orders --agent codex --detect-later
# Add a Git access token secret in the Draft's Secrets tab, then:
coder env generate orders

coder env generate <name> previews and fills an existing pending Draft using its saved repository and access. It accepts --starter, --serving-model, --database, --yes and --json. A pending Draft that already has its own setup.sh, pre-clone instructions or AGENTS.md keeps them and is generated with connection; --database local is refused there with local_database_draft_has_files, which names those files.

The preview's database entry reports the engines found, the choice in effect and the recipe: when a local database is proposed, its engine, server and version, idle memory estimate and seed status; otherwise a fixed code and message. --database is sent with the preview, so a choice that can't be used is refused before you are asked to confirm. When the Draft records a choice, the result adds a Database: line (in JSON, generation.database).

Creation uses the server's environment-lifecycle capability and Draft permissions. You need environments:manage on an environment and must also be allowed to manage the new Draft. A manager of only one existing environment cannot create an unrelated Draft. Filling a pending Draft requires manage permission on that Draft.

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.

In Full edition, Ask CoderFlow in the Web UI also lists containers started this way and can offer a button that opens a container's terminal or VS Code in the browser.

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, latest response, 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

coder results includes the agent's latest reply. Interactive replies appear as text choices with a hint for answering. Open the task in the Web UI to send your answer as a normal follow-up.

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.

coder reject --undo-device-changes first undoes the file changes the task made on your computer through CoderFlow Link.

• Only the task's owner can ask for this.
• Changes that cannot be undone are kept and listed with the reason, for example when the computer is offline or a file has changed there since. The rejection still completes.
• Effects of commands the agent ran are never undone.

coder reject <task-id> --undo-device-changes

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