Atlas

The Atlas CLI connects agents to your training account. Read your goals, gym notes, programs, and workout history; author plans and log training with explicitly approved access.

Install

Requires Node.js 22 or newer.

npm install -g @atlas-training/cli
atlas help
atlas --skill

The package is @atlas-training/cli; the command is always atlas. To run without a global installation:

npm exec --yes --package=@atlas-training/[email protected] -- atlas help

Connect

Published version 0.6.1 does not have connect. In Atlas, sign in and choose Agent access → Other agents → Create CLI setup prompt. Follow its private one-time enrollment instructions with auth enroll --file -, then auth login, approve Allow full access, and verify auth status and me. Reuse existing credentials; keep the token in stdin or a private file, never command arguments, URLs, logs, or Git.

Version 0.6.2 is an unpublished candidate. If you already have an installed CLI whose help lists connect, run:

atlas connect

Open data.approval_url from the JSON result, sign in to Atlas, and approve full training access once. The approval covers all current training API operations, including your profile, gym notes, plans, workouts, import, and export. It does not grant account administration or device control. Installation and a pending connection grant no training access.

After approval, run the same command again:

atlas connect
atlas --skill

Follow returned data.next_command commands to preserve your actual executable, Node launch flags, working directory, origin and credential directory without a registry download. The connected result identifies your account in data.account. Repeating atlas connect reuses the saved identity; it does not replace working keys. To wait for approval for up to 120 seconds, use atlas connect --wait 120. Approval remains active until you revoke the connection. Short-lived approval links limit setup, not the approved connection's lifetime.

The CLI connects to hosted Atlas at https://api.atlas-training.workers.dev by default. For another Atlas server, keep its exact origin on every network command, or set ATLAS_URL to that origin; --url overrides that setting. For local development:

atlas --url http://127.0.0.1:3000 connect

Remote connections require HTTPS.

Credentials stay private on the agent's machine under ~/.config/atlas, with separate identities per origin. Never put private keys in chat replies, logs, or version control. Disconnect an agent in Atlas Agent access or run atlas auth logout with the same origin. Full training access does not authorize unrelated work; agents must stay within your requested task.

Existing private setup prompts and auth enroll, auth login, and auth request remain available for manual integrations. Pass enrollment JSON through stdin or a private file, never command arguments. Those lower-level login/request commands require explicit capability names from atlas discover.

Agent handbook

The training handbook and research library ship with the CLI and work offline, before sign-in:

atlas --skill
atlas knowledge list
atlas knowledge get guides/connect
atlas knowledge search --query '{"q":"hypertrophy volume","limit":5}'
atlas knowledge get guides/safe-mutations

The agent supplies coaching and programming judgment. Atlas validates, versions, and stores records. It never controls exercise equipment or changes training merely to test a connection.

Historical workouts

CLI 0.6.2 adds commands for importing completed workouts on a server that advertises ensure_exercise, import_session, and read_session_import:

atlas schema import_session
atlas exercises ensure --file exercises.json --idempotency-key history-exercises-001
atlas sessions import --file session.json --query '{"dry_run":true}' --idempotency-key history-workout-001
atlas sessions import --file session.json --idempotency-key history-workout-001
atlas sessions import-status --query '{"provider":"source","namespace":"account","external_id":"workout"}'

Read atlas knowledge get guides/history-metrics for the payload contract. Import one historical workout and all its sets atomically, without supplying a program or workout object. Stable source IDs prevent duplicate imports; dry runs validate without saving. Run atlas connect again if an existing connection needs approval for the new operations. Preserve unknown observations and apparatus-specific exercise identities. Retain the mapping from earlier manual imports and reconcile those records before resuming them through this endpoint.

API discovery and output

atlas --url ATLAS_ORIGIN discover
atlas --url ATLAS_ORIGIN schema write_set
atlas --url ATLAS_ORIGIN sessions list --query '{"limit":20,"sort":"recent"}'

Commands emit one JSON envelope on stdout, except atlas --skill, which prints Markdown. Exit status is zero on success and one on failure. A successful connect result with data.status: "approval_required" still requires browser approval; data.status: "connected" confirms the account. Mutations require approved access and an idempotency key; updates also require the documented revision precondition. After an uncertain write, retry the identical request with the same key. The CLI does not automatically retry writes or overwrite stale revisions.

Update the CLI and its bundled knowledge with npm install -g @atlas-training/cli@latest.

Muse custom connector candidate

This source package also includes atlas-muse, a restricted egress-proxy adapter, and connectors/muse/atlas_muse/ with its generated skill, manifest and auth config. It is a release candidate; the published CLI may not include it yet. Read the bundled connector README for installation prerequisites before attempting to register it in Muse.

atlas-muse help and atlas-muse --skill describe its complete command surface. Muse's egress proxy supplies bearer authorization outside the CLI process. The adapter reads no key from environment, arguments, stdin or local config and pins requests to the declared provider host. atlas-muse status checks identity and server-reported permissions live; verify performs a connection check. New sets log/reps log operations enforce create-only writes; corrections use separately permissioned sets write/reps write. Hosted connection and Vault removal helpers remain unavailable until Muse's actual callable interface is provided. Manual set-token is unsupported on this privilege-separated path.