CLI reference

Every autolab command, argument, and option. This page is generated directly from the CLI, so it never drifts from the version you've installed. For the same text in your terminal, run:

autolab --help
autolab <command> --help

New here? Start with the Quickstart or the task-focused guides — they show these commands in context.

autolab

autolab — autonomous research from your terminal.

Create projects, queue experiments, and attach compute; the AutoLab agent writes code, runs jobs on your machines, and analyzes the results.

Usage:

autolab [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
--url	text	Control-node URL (overrides AUTOLAB_URL / profile).	None
--profile	text	Named profile from ~/.config/autolab/config.toml.	None
-q, --quiet	boolean	Print only essential results.	False
-v, --verbose	boolean	Stream raw git output.	False
--version	boolean	Show the version and exit.	False
--help	boolean	Show this message and exit.	False

autolab cancel

Cancel a queued or in-flight job.

Usage:

autolab cancel [OPTIONS] EXPERIMENT

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

autolab checkout

Reset the working tree to an experiment's code (or main).

Fetches first so the target commit is present locally; if you have uncommitted changes it explains how to keep them (submit) or discard them (--force).

Usage:

autolab checkout [OPTIONS] EXPERIMENT

Options:

Name	Type	Description	Default
-f, --force	boolean	Discard local changes when switching.	False
--help	boolean	Show this message and exit.	False

autolab clone

Copy a project's code into a local workspace. PROJECT is owner/project-slug.

Downloads the project's code (every experiment commit) into DIRECTORY — default ./<project-slug> — and links it to the project so status, log, checkout, and submit work inside it. It does NOT download experiment logs, metrics, or artifacts (see those with autolab log or on the dashboard — autolab open), and it never changes the project's state — a paused agent stays paused.

Usage:

autolab clone [OPTIONS] PROJECT [DIRECTORY]

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

autolab diff

Show what changed: ±lines per file; -p prints the lines themselves.

With no argument — your uncommitted changes vs the experiment you're in (new files included): exactly what autolab submit would send. With an EXPERIMENT id — what that experiment's code changed vs the code it branched from, e.g. autolab diff 9f2a01c4 after seeing it in autolab log.

Both summarize like git diff --stat — each changed file with its added/removed line counts; pass -p/--patch for the full patch. autolab's own .autolab/ control dir is never shown.

Usage:

autolab diff [OPTIONS] [EXPERIMENT]

Options:

Name	Type	Description	Default
-p, --patch	boolean	Print the changed lines themselves (a full git-style patch).	False
--help	boolean	Show this message and exit.	False

autolab graph

Show the experiment lineage tree — what branched off from where.

An experiment is a commit; this draws the branch relationships between them (the same graph as the dashboard). → marks the experiment you're in. Queued/pending experiments aren't shown — they have no lineage yet (use autolab log). Pass --format json for an edge list automation can read, or --root <id> to focus one experiment's subtree.

Usage:

autolab graph [OPTIONS]

Options:

Name	Type	Description	Default
--format	choice (text | json)	Output format: a tree (default) or JSON for automation.	text
--root	text	Show only the subtree rooted at this experiment (id-prefix).	None
--help	boolean	Show this message and exit.	False

autolab init

Create a project and link the current directory as its workspace.

First asks whether to use the current directory's code as the source, then collects the research goal:

• using code → name, run command, objective, env setup, constraints, termination • empty → name, objective, constraints, termination (the orchestrator fills run + setup once there's code)

The slug is the slugified name (deduped to …-v2 if taken). Every project starts on your AutoLab platform key. Fully scriptable with flags + -y (headless / LLM use); pass --start to go live now.

Usage:

autolab init [OPTIONS]

Options:

Name	Type	Description	Default
--name	text	Project name (the slug is derived from it).	None
--source	text	Git URL to clone (implies using code).	None
--empty	boolean	Start an empty project (ignore any local files).	False
--description	text	Short project description.	``
--objective	text	Research objective — what to optimize.	``
--run	text	How to run an experiment (code projects).	``
--prep	text	Environment setup (code projects, e.g. 'uv sync').	``
--constraints	text	Constraints the agent must respect.	``
--stop-policy	text	Termination condition (free text).	``
--max-cost	float	Hard $ cap on agent spend.	None
--start	boolean	Start the agent immediately.	False
-y, --yes	boolean	Non-interactive: use flags, don't prompt.	False
--help	boolean	Show this message and exit.	False

autolab install

Install the autolab skill into your coding agent (Claude Code and/or Codex).

Teaches Claude Code or Codex to drive this CLI — how to set up AutoResearch projects, queue experiments, attach nodes, and steer the agent. With no TARGETS it asks which tool(s) to set up; or name them directly:

autolab install                 # interactive: pick Claude Code / Codex / both
autolab install claude          # just Claude Code (~/.claude/skills/autolab)
autolab install codex           # just Codex ($CODEX_HOME/skills/autolab)
autolab install both --force    # both; overwrite an out-of-date skill

An existing file that differs is never overwritten without --force.

Usage:

autolab install [OPTIONS] [claude|codex|both|all]...

Options:

Name	Type	Description	Default
-f, --force	boolean	Overwrite an existing skill file that differs.	False
--dry-run	boolean	Show what would change — write nothing.	False
--help	boolean	Show this message and exit.	False

autolab keys

List your API keys (subcommands: add, use).

New projects default to your AutoLab platform key; keys use switches a project to one of your own provider keys.

Usage:

autolab keys [OPTIONS] [COMMAND] [ARGS]...

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

autolab keys add

Store a new provider API key on your account.

Usage:

autolab keys add [OPTIONS]

Options:

Name	Type	Description	Default
--provider	choice (anthropic | openai | google | openrouter | xai | deepseek | minimax | moonshot | glm | qwen)	Key provider.	None
--name	text	Display name for the key.	None
--value	text	Secret key value (omit for a hidden prompt).	None
--limit	float	Spending limit (USD).	None
--help	boolean	Show this message and exit.	False

autolab keys use

Assign one of your API keys to the current project. KEY = id-prefix or name.

Usage:

autolab keys use [OPTIONS] KEY

Options:

Name	Type	Description	Default
--model	text	Also set the model (e.g. 'openai/gpt-5.5').	None
--help	boolean	Show this message and exit.	False

autolab log

Show experiment history (newest first); → marks the experiment you're in.

Includes queued and pending experiments. The commit column stays empty until the code is final — the agent may still write or revise it.

Usage:

autolab log [OPTIONS]

Options:

Name	Type	Description	Default
--limit	integer	Max rows to show.	30
--help	boolean	Show this message and exit.	False

autolab login

Sign in and store an API token for this host.

Default is a browser sign-in. --token <tok> stores a token you already have (e.g. printed by autolab token or created on the dashboard's Access Tokens page) without a browser — ideal for an agent driving a remote box.

Usage:

autolab login [OPTIONS]

Options:

Name	Type	Description	Default
--token	text	Store this API token directly (no browser) — for headless / SSH / CI.	None
--help	boolean	Show this message and exit.	False

autolab logout

Remove the stored token for this host.

Usage:

autolab logout [OPTIONS]

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

autolab nodes

List execution nodes (subcommands: add, rm).

Usage:

autolab nodes [OPTIONS] [COMMAND] [ARGS]...

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

autolab nodes add

How to attach a machine as an execution node for this project.

A node clones the project's private code, so it registers with a researcher+ token — the runner reads AUTOLAB_TOKEN / serve --token / your stored login. serve detaches into the background; manage it with autolab serve status / autolab serve stop.

Usage:

autolab nodes add [OPTIONS]

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

autolab nodes rm

Remove an execution node (request shutdown + deregister). NODE = id/name.

Usage:

autolab nodes rm [OPTIONS] NODE

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

autolab open

Open the project dashboard (or an experiment page) in your browser.

Usage:

autolab open [OPTIONS] [EXPERIMENT]

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

autolab pause

Pause the agent (the autonomous loop). Resume with autolab start.

Usage:

autolab pause [OPTIONS]

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

autolab projects

List the projects you can access (for picking one to clone).

status is exactly what the project's card shows on the dashboard — Running / Idle / Paused / No LLM / No nodes / …

Usage:

autolab projects [OPTIONS]

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

autolab pull

Fetch the latest and fast-forward.

Usage:

autolab pull [OPTIONS]

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

autolab serve

Run this machine as an execution node (keeps running in the background).

Starts a background daemon and returns — the node stays connected after you close the terminal or SSH session. Manage it with:

autolab serve status     connection state + recent logs
autolab serve stop       disconnect this machine (--name for one node)
autolab serve log        this node's full runner log (-f to follow)

The node clones the project's private code, so it registers with a researcher+ token: --token, else AUTOLAB_TOKEN, else your stored autolab login. --foreground keeps the runner attached (dev/debug).

One daemon runs per node identity — machine + node name, where the default name is unique per GPU allocation. Separate Slurm/GPU sessions on one host (or several machines sharing an NFS home) therefore each get their own node: just run serve in each. Re-running serve on the same resource reports the existing daemon instead of double-serving it.

--type slurm (on a cluster login node) connects the whole cluster: the daemon scans partitions/QoS, reports them to the agent, and submits each experiment as an sbatch job — AUTOLAB_HOME must be on a filesystem the compute nodes share. --slurm-* set submission defaults; the agent can refine per run.

Usage:

autolab serve [OPTIONS] [COMMAND] [ARGS]...

Options:

Name	Type	Description	Default
--project	text	Project slug (owner/slug) to run jobs for.	None
--name	text	Node name (defaults to a derived name unique per machine / GPU allocation).	None
--poll-interval	integer	Poll interval in seconds.	5
--token	text	Researcher+ token to register with (else AUTOLAB_TOKEN / stored login).	None
--autolab-home	text	Root dir for workspaces (default ~/.autolab).	None
--type	choice (local | slurm)	Compute backend: local (this machine) or slurm (submit runs as sbatch jobs).	local
--slurm-partition	text	Default partition for sbatch jobs.	``
--slurm-account	text	Default account for sbatch jobs.	``
--slurm-qos	text	Default QoS for sbatch jobs.	``
--slurm-gres	text	Default --gres for sbatch jobs (e.g. gpu:1).	``
--max-parallel-jobs	integer	Concurrent runs a slurm node accepts (ignored for --type local).	4
--foreground	boolean	Stay attached to this terminal instead of daemonizing (Ctrl-C stops).	False
--replace	boolean	Stop the background node with this same name first, then start this one.	False
--help	boolean	Show this message and exit.	False

autolab serve log

Print this node's entire runner log (-n N for just the tail).

The log narrates everything the node does — registration, accepted jobs, agent bash commands, failures, shutdowns. The same log shows on the node's dashboard page. Rotated on each start; the previous run is kept next to it as serve.log.1.

Usage:

autolab serve log [OPTIONS]

Options:

Name	Type	Description	Default
-n, --lines	integer	Print only the trailing N lines.	None
-f, --follow	boolean	Keep streaming new lines (Ctrl-C exits).	False
--name	text	Show the node with this name (default: most recent).	None
--help	boolean	Show this message and exit.	False

autolab serve status

Show background nodes: liveness, project, logs, control-node view.

Records from other machines sharing the state directory (NFS) are listed read-only — their liveness can't be checked from here. Exits 0 when a daemon is running on THIS machine, 1 otherwise (scriptable).

Usage:

autolab serve status [OPTIONS]

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

autolab serve stop

Stop this machine's background node(s) and disconnect them.

Idempotent: cleans up stale state and reports if nothing was running. Records left by other machines sharing the state directory (NFS) are never touched unless targeted with --name (which clears the record only — the daemon itself must be stopped on its machine). An experiment mid-run is requeued once the control node sees the node offline.

Usage:

autolab serve stop [OPTIONS]

Options:

Name	Type	Description	Default
--name	text	Stop only the node with this name.	None
--help	boolean	Show this message and exit.	False

autolab settings

Show or edit project settings (subcommands: collab, delete).

With any flag, edits those fields then shows. Pass an empty string to clear a field, e.g. autolab settings --constraints "".

Usage:

autolab settings [OPTIONS] [COMMAND] [ARGS]...

Options:

Name	Type	Description	Default
--name	text	Display name.	None
--objective	text	What to optimize (the research objective).	None
--constraints	text	Constraints the agent must respect.	None
--run	text	How to run an experiment.	None
--prep	text	Environment prep (e.g. 'uv sync').	None
--description	text	Short project description.	None
--source	text	Source repo URL.	None
--coding-timeout	integer	Coding-step execution budget in seconds (120-7200; retried attempts get 2x). Raise it when env prep / smoke tests can't fit the default 600. Pass 0 to restore the default.	None
--help	boolean	Show this message and exit.	False

autolab settings collab

List collaborators (subcommands: add, rm, role).

Usage:

autolab settings collab [OPTIONS] [COMMAND] [ARGS]...

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

autolab settings collab add

Add USERNAME (a GitHub username) as a collaborator; re-run to fix the role.

Usage:

autolab settings collab add [OPTIONS] USERNAME

Options:

Name	Type	Description	Default
--role	choice (admin | researcher | viewer)	Role to grant.	researcher
--help	boolean	Show this message and exit.	False

autolab settings collab rm

Remove USERNAME from the project.

Usage:

autolab settings collab rm [OPTIONS] USERNAME

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

autolab settings collab role

Change USERNAME's role.

Usage:

autolab settings collab role [OPTIONS] USERNAME {admin|researcher|viewer}

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

autolab settings delete

Permanently delete this project on the control node (owner only).

Usage:

autolab settings delete [OPTIONS]

Options:

Name	Type	Description	Default
--yes	boolean	Skip the confirmation prompt.	False
--help	boolean	Show this message and exit.	False

autolab start

Start the agent on this project — and resume it after autolab pause.

The first start takes the project live: it seeds the baseline from your code (or, for an empty project, lets the agent code from your objective) and starts the autonomous loop. After that, start just resumes the paused loop.

Usage:

autolab start [OPTIONS]

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

autolab status

Where you are — the project (status, nodes, experiment counts) and the run you're in.

The status row is exactly what the project's card shows on the dashboard.

Start/pause the agent with autolab start / autolab pause; toggle idea generation with autolab status autogen on|off.

Usage:

autolab status [OPTIONS] [COMMAND] [ARGS]...

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

autolab status autogen

Show or toggle automatic idea generation (autogen on / autogen off).

When on, the agent proposes new experiments on its own; when off, it only runs what you queue. With no argument, prints the current agent + ideas state.

Usage:

autolab status autogen [OPTIONS] [on|off]

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

autolab submit

Queue an experiment. With code it snapshots + pushes the working tree; the control node fills in any blank fields (name/description now, run command + code at pickup).

By default every field you provide (including your pushed code) is locked — the research agent fills only the blanks and never overwrites your values. Pass --soft to let the agent refine what you set.

Usage:

autolab submit [OPTIONS]

Options:

Name	Type	Description	Default
-m, --message	text	Description / idea for this experiment.	``
--name	text	Experiment name (derived by the agent if omitted).	``
--run	text	Run command (agent fills it if omitted).	``
--setup	text	Setup command (e.g. 'uv sync').	``
--node	text	Node constraint (e.g. '8xH100').	``
--from	text	Base ref to branch from.	None
--priority	float	Queue priority.	None
--no-code, --nocode	boolean	Submit an idea only — ignore code changes; the agent writes the code. Requires -m.	False
--soft	boolean	Let the agent edit the fields you set (default: your fields are locked).	False
--help	boolean	Show this message and exit.	False

autolab token

Print the active token; subcommands manage PATs (create, ls, revoke).

Bare autolab token prints the token you're authenticated with — handy for bootstrapping a remote exec node without a browser:

TOK=$(autolab token create --name gpu-box)   # a fresh, revocable token
ssh gpubox "AUTOLAB_TOKEN=$TOK autolab serve --project alice/nanochat"

Prefer a named token create over the bare print so you can revoke just that one later. A token acts as you on every project you can access — pipe it, don't paste it where it'll be logged.

Usage:

autolab token [OPTIONS] [COMMAND] [ARGS]...

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

autolab token create

Mint a new personal access token. Prints the token (once) to stdout.

Usage:

autolab token create [OPTIONS]

Options:

Name	Type	Description	Default
--name	text	Name for the token (prompted if a TTY).	None
--help	boolean	Show this message and exit.	False

autolab token ls

List your personal access tokens.

Usage:

autolab token ls [OPTIONS]

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

autolab token revoke

Revoke a personal access token. REF = id-prefix or name.

Usage:

autolab token revoke [OPTIONS] REF

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

autolab update

Update this CLI to the build your control node serves.

Downloads the control node's current wheel and re-installs the tool with uv tool install --force — exactly what the install one-liner does. The control node stamps a fresh build (0.1.0.post<mtime>) on every deploy, so run this after the platform updates; it also syncs a machine back to an older build after a control-node rollback. A node daemon keeps its old code until restarted (autolab serve stop && autolab serve --project …, or serve --replace) — the command reminds you when one is running.

--check prints both versions and installs nothing; it exits 1 when this CLI differs from the control node's build (scriptable).

Usage:

autolab update [OPTIONS]

Options:

Name	Type	Description	Default
--check	boolean	Report versions only; install nothing.	False
--force	boolean	Reinstall even when already on the served build.	False
--help	boolean	Show this message and exit.	False

autolab whoami

Show the active host and signed-in user.

Usage:

autolab whoami [OPTIONS]

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False