# CoderFlow CLI

The CLI applies completed task patches to your local repositories. It complements CoderFlow Server by bridging server-based AI work with your local development.

## Installation

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

## Connecting to the Server

```bash
coder login
```

Enter your server URL and credentials when prompted.

## Applying Patches

Apply changes from a completed task to your local repos:

```bash
# Interactive selection from completed tasks
coder apply

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

# Apply only certain files
coder apply --include="*.js"
```

Changes are staged (`git add`) but not committed, so you can review before committing.

## Discarding Changes

Undo applied changes (unstage, restore, clean):

```bash
# Discard in default environment
coder discard

# Discard in specific environment
coder discard --env=myproject

# Skip confirmation
coder discard --yes
```

## Attaching to Containers

```bash
# Discover interactive containers and running containers retained by completed tasks
coder containers

# Include stopped, unknown-state, and active-task containers
coder containers --all

# Emit machine-readable output without a human-oriented preamble
coder containers --json

# Connect to last container
coder attach

# Connect with bash shell
coder attach --shell

# Connect to specific container
coder attach <container-id>

# Connect to a completed task's retained container without finding its container ID
coder attach <task-id>

# Show task state and retained-container state separately
coder status <task-id>

# Emit task and container status as JSON
coder status <task-id> --json
```

The default container list preserves existing interactive-container entries and
adds running retained-task containers. Retained entries show both task status
and container status plus an attach command using the public task ID.
Task-backed entries require both container-shell access and normal task
visibility; containers for private (`shared: false`) tasks are shown only to
owners who retain `tasks:view` or an administrator with `tasks:view_any`.
The `tasks:view_any` permission is independently sufficient for private-task
visibility.
When supplying a container ID directly, use the full ID or an unambiguous
prefix of at least 12 hexadecimal characters.

## Exporting and Importing Tasks

Export a task as a portable ZIP package:

```bash
coder export <task-id>
coder export <task-id> --output ./task-backup.zip
```

The package contains persisted task output and activity history, task metadata,
container logs, and a `/workspace` snapshot when the retained container is
available. Runtime-only server credential configuration is not included.

Import an export package or a plain local workspace directory:

```bash
# Restore the task in the state it was exported in (default)
coder import ./task-backup.zip

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

# Store the package as a reusable objective, or launch immediately
coder import ./task-backup.zip --mode=objective
coder import ./task-backup.zip --mode=running
```

Import modes are `preserve` (the default), `objective`, `staged`, `running`,
and `completed`. `preserve` reproduces the exported state: a finished task
imports as a finished task, an objective as an objective, and anything else —
including a plain workspace directory, which carries no state — as a staged
task. Use `--environment`, `--name`, `--agent`, or `--instructions` to override
package metadata. In the Web UI, **Import** creates an objective from the
Objectives view and preserves the exported state everywhere else.

A restored task keeps its transcript, its follow-up history, and its changed
files: the changed-files list is recomputed against the destination's own
repositories once the workspace is restored, so the Changed Files tab and the
approve dialog are populated as soon as the import finishes.

Continuing an imported conversation replays it rather than resuming it. An
agent session belongs to the container that created it, and the destination
container has never run the agent, so the first message after an import hands
the agent the imported transcript as context — the same mechanism a forked task
uses.

## Configuration and Profiles

Manage connection settings:

```bash
# Show current config
coder config show

# Set server URL
coder config set serverUrl http://myserver:3000
```

Use profiles to connect to different servers:

```bash
# Create profile
coder profile create production

# Switch profiles
coder profile switch production

# Use profile for one command
coder --profile=production apply
```

## Getting Help

```bash
# General help
coder --help

# All commands
coder --help-all

# Help for specific command
coder apply --help
```

Task management commands are available for when you prefer CLI over the Web UI. Run `coder --help-all` to see `run`, `status`, `results`, `list`, and more.