@synsci/atlas

The Atlas CLI for the Synthetic Sciences research map. Run experiments, capture evidence, search indexed sources, ask grounded questions, and let coding agents drive Atlas without a separate transport.

npm i -g @synsci/atlas
atlas login
atlas doctor
atlas init

That's the entire setup. atlas login opens a browser, redeems an Atlas API key, and writes it to the local profile config. atlas doctor checks auth, backend reachability, integration freshness, and bundled skills. atlas init find-or-creates the project for the current repo/folder and writes atlas.json, the opt-in activation contract for ambient research behavior.

When atlas.json is present, coding agents can stay mostly invisible while still adding value: load atlas brief when context matters, auto-scope library:* to project sources, use web:* as an Atlas-metered search/fetch path, and append compact breadcrumbs with log:*. If Atlas is unavailable, unauthenticated, over quota, or not relevant, agents should fail open and keep working normally.

What it looks like

Atlas now renders human-friendly output by default when you're at a terminal. Pipe the same command and you get JSON for scripting.

$ atlas key:list
   NAME                              PREFIX        CREATED  LAST USED  STATE
─  ────────────────────────────────  ────────────  ───────  ─────────  ───────
●  atlas-cli                         thk_856dc108  3d ago   just now   active
●  synsci · darwin · Aayams-MacBoo…  thk_d41ccc8e  3d ago   17h ago    active
·  old-key                           thk_28a2d4a0  7d ago   8d ago     revoked

2 active · 1 revoked

$ atlas library:list
ID        STATUS       TYPE             NAME                              UPDATED
────────  ───────────  ───────────────  ────────────────────────────────  ───────
dded7078  ● completed  documentation    ModalDocs                         1mo ago
d36f499b  ● completed  research_paper   GShard: Scaling Giant Models…     1mo ago
e3ea6910  ● error      research_paper   Attention Is All You Need         1mo ago

3 sources · 1 errored (atlas library:retry <id> to re-run)

Force a format with --format=json|tsv|csv|table|pretty. Set default_format in your profile with atlas config:set to make it sticky.

Quick reference

Look at what's there

atlas project:list                 # find a project root (slug or UUID)
atlas log:tail                     # recent project research-log entries
atlas node:list                   # every node you can see
atlas library:list                 # every indexed source
atlas key:list --active-only      # API keys, only the live ones
atlas usage:summary                # quota usage for the current billing period
atlas integrations:status          # github / wandb / huggingface connections

Drill in

atlas node:show --node able-helm-1359        # slugs work everywhere
atlas map:summary --node able-helm-1359       # rendered map summary
atlas map:tree --node able-helm-1359 --max-depth 3
atlas exec:list --node able-helm-1359
atlas evidence:list --node able-helm-1359

--node is an alias for --node-id; --project for --project-id. Slugs (able-helm-1359) and UUIDs both work — the CLI resolves slugs automatically via /nodes/resolve-by-slug before dispatch.

Write

atlas log:append --title "why we changed the eval" --body @note.md
atlas note:add --project able-helm-1359 --text @notes.md
atlas run:record --project able-helm-1359 \
  --title "lr=3e-4 seed=17" \
  --config-json '{"lr":3e-4,"seed":17}' \
  --metrics-json '{"val_loss":2.31}' \
  --outcome success
atlas node:create --payload-json @new-node.json
atlas evidence:add --node able-helm-1359 \
  --items '[{"local_path":"report.md","artifact_type":"text"}]' \
  --expected-revision 4

Compare runs

run:compare renders a matrix across runs in a project. Columns can be node fields or dot-paths into the run data (config.lr, metrics.val_loss):

atlas run:compare \
  --root able-helm-1359 \
  --cluster resnet50/cifar10/lr-sweep \
  --columns title,config.lr,metrics.val_loss,outcome \
  --format=table

Pair with --run-cluster-key on run:record so identically-shaped experiments fold into one comparable axis.

Ambient search/fetch

atlas library:search --query "windowed attention with global tokens"
atlas web:search --query "latest ARC-AGI public leaderboard" --num-results 5
atlas web:fetch --url https://example.com/paper

Inside an atlas.json project, library:*, web:*, and log:* auto-fill the project/source context where possible. The web commands are intended as a provenance-capturing alternative to ad hoc WebSearch/WebFetch when the result should belong to the project.

Optimize an artifact (GEPA loop)

When there's a single artifact and a quantitative benchmark, hand the tuning to GEPA — every candidate lands in the map with lineage, a per-example scorecard, the exact commit, and a live budget on the control node:

atlas optimize:start \
  --target prompts/classify.txt \
  --benchmark "python eval.py --candidate {target}" \
  --objective "maximize spam F1 on the holdout set" \
  --gate "pytest tests/core -x" --ground --parallel 4

atlas optimize:status --node <control>      # budget, best, stall
atlas optimize:stop   --node <control>      # graceful mid-run stop
atlas run:chart --project <control> --metric metrics.score

# Before claiming a result, referee it: N replications at the candidate's
# exact commit, mean/std + one-sided t-test, referee-report node.
atlas optimize:verify --node <control> \
  --benchmark "python eval.py --candidate {target}" \
  --seeds 10 --threshold 0.9 --metric max

--parallel K evaluates K candidates concurrently; --resume <control> continues a campaign from its best recorded candidate. --ground consults your indexed library when the search stalls and folds the answer into GEPA's reflection. Requires uv + a reflection-LM key. Already running gepa yourself? Add the bundled AtlasCallback (see the atlas-optimize skill) to stream any run into the map — one line.

Search and ask

atlas library:add --type research_paper --url https://arxiv.org/abs/1706.03762
atlas library:search --query "windowed attention"
atlas library:ask    --query "what does Switch Transformer route on?"
atlas research:ask   --query "compare MoE routing across recent papers"
atlas library:retry  --source-id <id>     # re-trigger a stuck index

Capture code

atlas github:link                          # connect your GitHub account
atlas repo:capture --node able-helm-1359 \
  --repo-url "$(git remote get-url origin)" \
  --branch-name "$(git rev-parse --abbrev-ref HEAD)" \
  --head-commit-sha "$(git rev-parse HEAD)" \
  --pin true

repo:capture records the exact code state behind a node. --pin creates an immutable tag on the repo so a public-graph viewer can always re-open the exact commit; pins persist into the node's code-state and travel with node:branch, map:export/import, and fork. atlas reproduce --node <id> --check prefers the pinned tag and fails when the commit is not reachable on the remote.

Share and fork graphs

Sharing is graph-scoped: visibility and collaborators live on the project root, and every descendant inherits them — child nodes have no separate visibility.

atlas node:share --node <project-root> --visibility public  # private | unlisted | public
atlas access:set  --node <project-root>                      # viewer | editor | admin collaborators
atlas fork        --node <public-root-or-node>              # copy a visible graph into your account

atlas fork copies any visible node/subtree into your account as a new private graph, preserving code-state and provenance — browse a public graph, then fork and continue from it. No export/import dance.

Install bundled skills into your coding agent

atlas install                # interactive picker (Claude Code, Cursor, Codex,
                             # Windsurf, Aider, Continue, Goose)
atlas install --dry-run      # print the plan first
atlas install --agent=claude-code,cursor   # non-interactive
atlas install --no-hooks     # skills only, skip the ambient logging hook
atlas install --uninstall    # cleanly remove (skills + hooks)

On Claude Code and Cursor, atlas install also wires a post-tool hook (matcher WebSearch|WebFetch) that records the agent's web activity to the project research log automatically — a strict no-op outside an atlas.json project, and respecting auto.enabled/auto.log. This is the deterministic half of the ambient layer: provenance without the agent having to remember to call Atlas. --no-hooks opts out; --uninstall removes it cleanly.

Symlinks where the agent reads a directory of SKILL.md files (Claude Code). Whole-file adapter for Cursor/Aider/Continue/Goose. Managed block inside Codex AGENTS.md and Windsurf global_rules.md — pre-existing content outside the markers is preserved exactly.

Profiles, keys, secrets

atlas whoami                           # email, name, key prefix
atlas config:set --base-url <url>      # point at a different environment
atlas config:list                      # all local profiles
atlas key:create --name "ci-runner"   # mint a new API key
atlas secrets:set < key.txt            # store a key in macOS Keychain

Output formats

| Format | When | Notes | |-----------|------------------|-------| | pretty | TTY default | Per-command views (status glyphs, relative times, status footers). | | json | Pipe default | Lossless — every field, no truncation. Always available with --format=json. | | table | Opt-in | Same per-command views as pretty, without color. | | tsv/csv | Opt-in | One row per item; nested objects stringified. |

atlas node:list                  # pretty when you're at a terminal
atlas node:list | jq '.nodes[0]' # json automatically when piped
atlas node:list --format=json    # force json (always)

Errors and discovery

The CLI translates raw backend responses into actionable messages and points at a discovery command when you forget a flag:

$ atlas map:summary
--node is required — try `atlas node:list` or pass a slug like `able-helm-1359`

$ atlas note:add
--project is required — try `atlas project:list` to find one

$ atlas node:show --node bogus
Invalid ID format (node:show). Atlas IDs are UUIDs — try `atlas node:list` to
find one, or pass a slug (e.g. able-helm-1359).

atlas doctor checks integration freshness too — expired GitHub tokens are surfaced as warnings instead of pretending everything is OK.

Environment variables

| Variable | Purpose | |----------|---------| | ATLAS_API_KEY | Override the stored API key for this invocation. | | ATLAS_BASE_URL | Point at a non-production API. | | ATLAS_CLI_CONFIG_PATH | Alternate profile config file. | | NO_COLOR / FORCE_COLOR | Disable / force ANSI color in pretty output. | | ATLAS_LOGIN_TIMEOUT_MS | Browser-login wait timeout (default 5 min). |

Command surface

Commands are grouped by domain. The "other" catch-all is gone — every command lives in a real group:

• auth · login, logout, whoami, doctor, secrets:*
• config · config:list, config:show, config:set, config:unset
• account · account:update
• setup · init, install
• map · node:*, map:*, link:*, access:*, draft:*, label:*, project:list, program:snapshot, history:export
• share · node:share (graph-scoped visibility), access:set/set-bulk (viewer/editor/admin), fork (copy a visible public graph into your account)
• evidence · evidence:*
• research-loop · brief, hypothesis:add/update, experiment:plan, decision:add, eval:define, reproduce
• runs · run:record, run:compare, run:chart, run:spool:*, leaderboard (managed executions: exec:start/list/stop)
• optimize · optimize:start, optimize:status, optimize:stop, optimize:verify, optimize:progress (GEPA loop over an artifact, recorded into the map; verify = N-seed referee)
• journal · note:add, notebook:cell, log:*
• integrations · github:*, integration:*, repo:capture, repo:pin, repo:push
• keys · key:create, key:list, key:rotate, key:delete
• library-research · library:*, web:*, research:*, usage:summary
• agent · agent:run
• ops · ops:maps:* (admin)

atlas help                               # text listing
atlas help <command>                     # text help for one command
atlas help <command> --schema --format=json  # full request shape
atlas help --format=json                 # the full command catalog

Skills

Nine bundled CLI-only Atlas skills ship in the package:

| Skill | Use when the user wants… | |-------|--------------------------| | atlas | Base guidance + the skill router; map reading commands. | | atlas-lab | "Log this run" / "continue the research" — the loop: brief → hypothesis → plan → record → compare → decide. | | atlas-frontier | "What's next?" (plan-only) or "keep going" (autonomous, budgeted). | | atlas-optimize | "Make this faster/better against a metric" — the GEPA loop over one artifact. | | atlas-autoresearch | "Prove it / publish it" — refereed campaign: researchify → pre-register → search → verify → report. | | atlas-map | "Turn this paper/repo into the map" — source-to-nodes authoring. | | atlas-search | "Search/ask our sources" — library search, grounded Q&A, deep research. | | atlas-reproduce | "Reproduce/validate this claim or result." | | atlas-paper | "Turn this graph into a paper" — draft a publication-style manuscript from graph claims, runs, evidence, sources, and code-state. |

atlas install drops these into every coding agent on the machine.

Agent onboarding

If you want a coding agent to onboard a new user, paste this prompt:

You are an agent onboarding me to Atlas by Synthetic Sciences — the research map
where my experiments, hypotheses, evidence, and decisions live permanently. Set
it up end to end:

1. `npm i -g @synsci/atlas@latest`, then `atlas login` and ask me to approve in
   the browser when it opens.
2. `atlas doctor --format=json` — verify auth, backend, and the nine bundled
   skills (atlas, atlas-lab, atlas-frontier, atlas-optimize, atlas-autoresearch,
   atlas-map, atlas-search, atlas-reproduce, atlas-paper). Then `atlas install` to wire them
   into this agent.
3. `atlas init` — bootstrap the project for this folder/repo (dedupe-safe,
   re-runnable) and write `atlas.json` so ambient Atlas behavior is opt-in to
   this project.
4. `atlas brief --project <id>` — load the context packet and summarize it for
   me: open hypotheses, recent runs, failures, decisions, and suggested next.

House rules: the skills are bundled in the CLI — never configure separate skill
downloads or legacy host transports. Commit code before recording runs (code
state is auto-captured onto every run). Never print my full API key into shared
logs — summarize the key prefix, storage location, CLI version, doctor result,
and skill count when setup is complete.

Agents should inspect command metadata with atlas help --format=json and per-command request shapes with atlas help <command> --schema --format=json.

Links

• App: https://app.syntheticsciences.ai
• Docs: https://docs.syntheticsciences.ai
• Issues: https://github.com/synthetic-sciences/atlas/issues

MIT licensed.