CLI Reference
The package exposes two equivalent commands:
co-auto-research
auto-research
These commands are available after installing the npm package:
npm install -g co-auto-research
To update:
npm install -g co-auto-research@latest
Source-checkout development commands are covered in the contributor guide.
Commands
Command |
Purpose |
|---|---|
|
Copy the template into a new empty project directory. |
|
List generated projects under the current folder and |
|
Reopen the UI for an existing generated project. |
|
Start the local web UI. |
|
Start a dashboard over several generated projects. |
|
Install the Cloudflare tunnel CLI into the user directory on Linux, without sudo. |
|
Install the Linux proxy helper used when |
|
Check local prerequisites and port availability. |
|
Print installed version, detected project template version, and npm update command. |
|
Sync core reviewer and trial-protocol instructions in an existing project, with backup. |
|
Print the installed CLI package version. |
Start the UI
co-auto-research ui
Inside a generated project, this serves that project using the package-managed
UI runtime. Outside a generated project, it creates or serves co-autoresearch-projects/
as a dashboard.
Project Dashboard
co-auto-research ui --projects-dir ./projects
The dashboard lists generated projects directly inside ./projects and can
create new projects from the UI.
Return to Existing Work
co-auto-research ls
co-auto-research attach my-project
ls scans the current directory, immediate generated-project children, and a
co-autoresearch-projects/ dashboard folder when present. It prints project names,
statuses, and paths.
attach resolves a project by display name, directory name, path, or project ID
prefix, then starts the same UI server that ui --project <path> would use.
This is the normal command when you closed the browser or terminal yesterday and
want to continue a previous project today.
If you keep projects somewhere else:
co-auto-research ls --projects-dir ./projects
co-auto-research attach my-project --projects-dir ./projects
Autoresearch Commands
The dashboard exposes these as buttons, and the composer also accepts the same slash commands:
Command |
Meaning |
|---|---|
|
Show the current autoresearch state. |
|
Resume the loop from the latest active trial. |
|
Let the current turn finish, then prevent the next trial from starting. |
|
Confirm, archive the current trajectory, and start a new Trial 1. |
|
Show session and gate status. |
|
Show running process state. |
|
Show changed files. |
/goal restart is not a lightweight reset. It archives existing trials, runtime
state, working manuscript, generated workspace, and current findings under
archive/restarts/. User-uploaded or user-confirmed resources remain available;
autoresearch-discovered or generated resources become prior-run context until
you explicitly reattach or confirm them.
The dashboard ships with Ivory and Nocturne themes. The setting is local to the browser and does not clear composer text, attachments, or context chips.
Update Project Instructions
The npm package updates the CLI and UI runtime. Existing project research files
are not rewritten automatically, but core reviewer and trial-protocol
instructions can be synced when doctor or the UI reports an outdated
instruction baseline:
co-auto-research upgrade-project
For a dashboard folder:
co-auto-research upgrade-project --all --projects-dir co-autoresearch-projects
The command backs up previous core reviewer and protocol files under
archive/template_migrations/ and preserves custom extra reviewer or
instruction files outside the managed core set.
Port and Browser Options
co-auto-research ui --port 8780
co-auto-research ui --no-open
co-auto-research ui --open
co-auto-research attach my-project --port 8780
If the requested port is busy, the server tries the next available port and prints the actual URL.
Remote Mode
co-auto-research ui --remote
co-auto-research ui --remote --proxy http://10.21.11.21:8888
Remote mode is for SSH-accessible servers. It keeps browser launch disabled on
the server, keeps the UI bound to 127.0.0.1, and prints a temporary
Cloudflare browser link. Install the official cloudflared CLI on the remote
server for this one-command browser access.
If cloudflared is missing, the command prints a short Cloudflare CLI setup
guide with install, run, and check commands. Keep the terminal open while using
the link.
On Linux servers that require an HTTP proxy for internet access, CoAutoResearch
detects COAUTO_REMOTE_PROXY, HTTPS_PROXY, or HTTP_PROXY and runs
cloudflared through graftcp with --protocol http2. If the proxy helper is
missing, the CLI prints co-auto-research install-graftcp before starting the
UI server.
If Cloudflare is blocked on the server, set COAUTO_REMOTE_MODE=ssh to force
SSH-only remote mode. In that fallback path, the command uses
user@<ssh-host> unless COAUTO_REMOTE_TARGET is set, because server
hostnames are often not valid SSH aliases from your laptop.
Environment Variables
Variable |
Purpose |
|---|---|
|
Python executable used to start the UI server. |
|
Force the runtime backend for UI-launched agent runs: |
|
Explicit Codex executable path. |
|
Alternate Codex executable path. |
|
Explicit Claude Code executable path. |
|
Alternate Claude Code executable path. |
|
Used by the Codex |
|
Used by the Claude |
|
Used by Claude gateway providers such as Z.AI GLM or custom Anthropic-compatible gateways. Not passed to Codex runs. |
|
Disable automatic browser launch. |
|
Explicit |
|
Override the standalone |
|
Explicit |
|
Override the standalone |
|
HTTP proxy used for proxy-aware |
|
Set to |
|
Set to |
|
Override the SSH target printed by the SSH fallback path, for example |