The ros command line

Everything the app does, scriptable. The CLI and the app share the same stores — they can never drift apart. This page shows the most-used flows first, then the full command list; every command and subcommand answers --help.

Workspaces & capture

ros init ~/project          # create a workspace
ros status                  # what's in here
ros run "python train.py --lr 0.05" -n baseline -p lr=0.05 -s 42 -t demo
ros list-runs               # the run board
ros show <run-id>           # everything about one run
ros diff <run-a> <run-b>    # what changed between two runs
ros trace <run-id>          # provenance of a run
ros pack <run-id>           # replayable repro pack
ros replay <pack.zip>       # re-execute a pack in a fresh environment
ros flow pipeline.yaml      # multi-stage runs, linked
ros run --notebook analysis.ipynb -p lr=0.05   # Jupyter, headless + captured

--notebook executes the notebook through your own environment's Jupyter (papermill, when installed, injects the -p parameters for real); the executed copy — outputs included — lands as an artifact of the run. Inside an interactive notebook, %load_ext researchos.jupyter gives you the %%ros cell magic: the cell runs normally and is recorded as a run (source archived, params from the magic line, metrics via ros_log(acc=0.93)) — it captures what the cell did, not a replayable pipeline; use --notebook for that. The magic needs the researchos Python package importable in the kernel.

Runs go through your project's environment automatically: a workspace .venv, environment.yml (conda run), uv.lock or poetry.lock is detected for CLI, app and remote runs alike (ROS_NO_VENV=1 opts out), and capture records the interpreter the command actually resolves to — not the daemon's. Non-Python commands capture too: R, Julia and Node versions are recorded when the command or the workspace's lockfiles point to them.

Knowledge

ros note new "Title" --log --mood 4 --time 90   # logbook entry
ros note seal <note-id>     # tamper-evident seal
ros note verify             # verify the whole chain
ros note timestamp <note-id>   # RFC 3161 anchor for a sealed entry
ros note probative <note-id>   # self-contained evidence package
ros bib add 1706.03762      # arXiv/DOI import with PDF
ros bib import-zotero --path ~/Zotero
ros paper new "Title" && ros paper insert-cite vaswani2017
ros paper check             # figures still match their runs?
ros paper export --pdf

Figures for your paper (LaTeX, Word…)

ros assets follow baseline loss.png --as fig-loss.png   # track the newest 'baseline' run
ros assets add <artifact-id> --as fig3-frozen.png        # or pin one exact artifact
ros assets export            # → paper-assets/ + provenance.{json,md,tex}
ros assets list              # the mappings (stored in ros-assets.json)

Your document includes the files from paper-assets/ by their stable names; re-run the experiment, export again, recompile — the figure updates in place. provenance.tex and .md carry the figure-to-run table (run id, parameters, date) ready to paste as an appendix. Works with any editor — LaTeX, Word, LibreOffice, Beamer — because it is just a folder of files.

Slides for your next meeting

ros slides                    # slides.md (Marp) from the last 14 days
ros slides --pinned --format beamer -o deck.tex
ros slides --runs run_a,run_b # exactly these runs

One slide per run — title, parameters, results, figures, run id — plus a closing provenance table: every claim in the deck stays one step from its evidence. Markdown decks render with Marp (or any Markdown-slides tool); Beamer compiles with your usual LaTeX toolchain. Also available from the Paper screen in the app.

Records & reports

ros timeline --project aim2      # the whole chronology, merged
ros report --from 2026-07-01     # progress-report draft for a meeting
ros transmission -o handover.zip # complete project handover, open formats

Planning

ros todo add "Write results" --due 2026-08-02 --priority
ros todo add "Backup" --every weekly
ros agenda list             # the next 14 days
ros agenda export-ics       # to any calendar app
ros overview                # all workspaces at once

Sync & account

# Beta server: https://sync-dev.tramea.org (invite code required)
ros account register you@lab.org --server https://sync-dev.tramea.org --invite <code>
ros account login you@lab.org --server https://sync-dev.tramea.org
ros account recover you@lab.org --server …   # recovery-code reset
ros account passphrase      # rotate passphrase + recovery code
ros sync enable             # this workspace ⇄ the server
ros sync now                # one push-pull-blobs cycle
ros sync status             # sync state for this workspace

On a second computer, log in with the same account, then recreate any synced workspace with its full history:

ros sync spaces             # what's on your account
ros sync join my-project -p ~/my-project

Project files & remote runs

ros sync files on           # scripts and data travel as encrypted blobs
ros sync files status       # what's synced, what's excluded
ros sync remote-exec on     # let THIS machine execute queued runs
ros run --remote "python train.py --lr 0.07"   # queue from any other computer

Project files sync carries working files up to 50 MB each by default, honors a .rosignore file, and always excludes .git. ros run --remote queues the run on an executor machine of the same synced workspace; results sync back as an ordinary run. Details in Sync & security.

Shared spaces & sharing

ros lab create thesis-duo              # a shared (Duo) space, up to 3 people
ros lab invite colleague@lab.org       # seal the space key to their devices
ros publish <element-id> --to thesis-duo   # share ONE element
ros share colleague@lab.org            # share a whole workspace
ros invites list                       # invitations waiting for you

Labs: directory, conversations, governance

A full lab — teams, a member directory, governance — is the Lab plan's organization layer, provisioned at onboarding. Inside one, the ros lab group grows an org toolset:

ros lab directory                 # teams, people and team spaces
ros lab profile --interests "…"   # opt-in expertise profile, hand-curated
ros lab search diffusion          # find colleagues by what they published
ros lab dm colleague@lab.org "…"  # E2EE direct message (thread on first use)
ros lab conversations             # your DMs and group chats on this machine
ros lab messages <space-id>       # read a thread
ros lab team-space NAME --team <id>   # org-owned team workspace (lead/admin)
ros lab project-space NAME        # cross-team project space (any member)
ros lab team-invite colleague@lab.org --team <id>   # every team space at once
ros lab publish-report            # post your progress report to the space
ros lab overview                  # admins: activity overview — metadata only
ros lab org-audit                 # admins: org-wide audit trail
ros lab announce-sync             # invite members missing from announcements

Conversation invites are accepted automatically by the recipient's daemon — messaging a colleague just works, no accept step. Outside a lab, ros lab dm reaches anyone you already share a space with (the server enforces this). Messages are end-to-end encrypted like everything else; admins' overview and audit see metadata only.

The daemon, API and web UI

ros api --daemon            # background daemon: REST API, sync, remote runs
ros api --status            # is it running?
ros api --stop
ros ui                      # server-rendered web UI in your browser

The desktop app talks to the daemon; installed packages start it at login on Linux and Windows. The API is loopback-only and protected by a bearer token — interactive docs at http://127.0.0.1:<port>/v1/docs.

The assistant (optional)

ros ask --provider anthropic --set-key sk-…   # your own API key
ros ask "what did I try last week?"           # AI over your workspace
ros ask --provider hosted "which run had the best F1?"   # plan credits

Three ways to power it: your own key with Anthropic (Claude), OpenAI (GPT), Google (Gemini) or Mistral — one key per provider, stored on your machine, prompts go straight to the provider; hosted — your plan's included credits (10 questions per month during the beta), relayed by your sync server to the model provider and forgotten, never stored; or lab — your lab's own model, when your lab has configured one, so prompts never leave the lab network. Elements you lock stay invisible to all of them (ros ask --set-default locked makes everything opt-in).

Escape hatch

ros export --all            # plaintext archive of everything

Every top-level command

One line each, as printed by ros --help (v0.12.0). Groups list their subcommands with ros <command> --help.