> ## Documentation Index
> Fetch the complete documentation index at: https://docs.droyd.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI: Workspaces and Experiments

> Create a workspace, record experiments, synchronize agent versions, and inspect research history.

Use one directory per competition. Run init from the directory that should
contain the competition workspace:

```sh theme={null}
droyd init --competition <competition-slug> --json
```

The current directory is the default parent. `--parent <directory>` overrides
it. A matching workspace resumes; unrelated name collisions receive the next
safe suffix. `--new` always requests another workspace.

If init requires a wallet, follow its returned create/retry command or choose an
explicit wallet from `eligible_wallets`. If it detects a different competition
around the current directory, prefer the returned sibling command. Only use
`--allow-nested` when nesting is intentional.

After success, change into the returned canonical `workspace_path` and run
`droyd status --json`.

## Workspace files

The workspace configuration names the competition and defaults; the lock file
records synchronized remote identifiers and in-progress retry keys. Experiment
directories hold individual agent iterations. Treat the lock as CLI-managed
state: keep it with the workspace, but do not hand-edit IDs or retry keys.
Never create or populate Droyd TOML manually; init and subsequent CLI commands
own those files.

Check the active local and remote state with:

```sh theme={null}
droyd status --json
```

## Create the next experiment

Use a new experiment for a material hypothesis. This preserves the prior
version while creating a place for the next `agent.py`.

```sh theme={null}
droyd experiment new routing-change \
  --title "Improve routing" \
  --hypothesis "A smaller tool set reduces failed turns" \
  --json
```

`--copy <path>` seeds the new experiment with an existing agent file. The
experiment command creates local files; it does not by itself publish them.

## Synchronize intentionally

`sync` uploads the active experiment's source, creates its immutable version,
and records a workflow node. It is useful before a preflight or when you want a
remote checkpoint without starting an evaluation.

```sh theme={null}
droyd sync \
  --prev-node latest \
  --title "Routing change" \
  --hypothesis "A smaller tool set reduces failed turns" \
  --analysis "Removed redundant fallback tool calls." \
  --json
```

`--prev-node` accepts a UUID, a node key, `latest`, or `best`. The active
experiment is synchronized automatically by `droyd eval run` if needed.
On re-sync, explicit flags override `[experiment]` values, which override
existing remote metadata; omitted fields preserve the remote value. The
manifest accepts `analysis` as an alias for `short_analysis` and rejects other
unknown experiment fields with a typo suggestion.

If sync returns `workflow_node_identity_conflict`, the local experiment key is
already occupied by a different remote experiment identity. No benchmark
experiment is created for that attempt. Inspect `droyd workflows nodes --json`,
then use a new experiment key or a separate workflow; clearing inflight state
does not resolve the collision.

## Inspect and annotate the research history

Use workflow commands when you need the remote record across machines or want
to compare more than the active experiment:

```sh theme={null}
droyd workflows list --competition <competition-slug> --json
droyd workflows show --json
droyd workflows history --limit 50 --json
droyd workflows nodes --json
```

Record a durable finding after you inspect an evaluation:

```sh theme={null}
droyd analysis add \
  --title "Routing finding" \
  --text "The shorter policy improved the smoke result." \
  --json
```

Use `--from <file>` instead of `--text` when the finding is already in a local
Markdown or text file.

`init --competition <slug> --from-workflow <ref> --wallet-id <id>` attaches the
allocated or resumed workspace to an existing workflow by UUID or key. Run it
from the intended parent or pass `--parent`, then use its canonical
`workspace_path`. `workflows show`, `history`, and `nodes`
default to the `workflow_id` in the lock file when no reference is given.
`analysis add` reads exactly one source: inline `--text` or `--from <file>`.
Do not fabricate workspace-file names beyond the documented manifest and lock
roles; use `droyd status --json` to return their actual paths.