CLI reference

Commands use the discovered project root unless you pass --root PATH. Run cor COMMAND --help for the executable’s full help. These defaults describe v0.1.0.

Global options

Successful connections save the key path and host fingerprint privately by exact remote URL. Private keys are never copied. Load encrypted keys with ssh-add.

current

cor current

Current creates a persistent SSH host key. On first start it authorizes the first conventional local public key if present; otherwise access stays denied until a key is added. Keep current in a terminal or use your own process supervisor.

keys and whoami

cor keys add teammate.pub --person alice --name "Alice"
cor keys list
cor keys remove SHA256:...

Use keys --data PATH for a custom server data folder. Changes apply without restart, including to future requests on existing connections. Already running requests may finish.

cor whoami

Print your display name, person ID, and authenticated SSH fingerprint. JSON includes fingerprint, person, name, key_label, and authorized.

Use keys add FILE --person ID --name NAME to name a person once; --name requires --person and otherwise defaults to the ID. Reuse --person for their other keys. IDs contain 1–48 lowercase letters, digits, underscores, or hyphens. keys assign FINGERPRINT PERSON --name NAME labels an existing key without granting access. Bindings cannot move to another person.

Use current --checks /path/to/corotation.json once to pin required publication checks. The policy is saved in the server data directory. Native commands require the explicit --allow-native-checks option; presets use Docker.

repo

cor repo create my-game
cor repo create another-project --key teammate.pub
cor repo list
cor keys --repo my-game add teammate.pub --person alice

All repositories share the same SSH address and port. Each has independent files, chunks, checks, sessions, baselines, people, and access lists. Names use 1–64 lowercase letters, digits, hyphens, or underscores. The existing data root remains default; named repositories live under repositories/NAME. At most 128 repositories are supported.

With no --key flags, creation copies default's current authorized keys and names once. Explicit keys replace that initial membership. Changes apply while current runs. For a custom server folder, use repo --data PATH create NAME and keys --data PATH --repo NAME. Add --checks /path/to/corotation.json when creating a repository to configure its own required checks; native commands need the server's --allow-native-checks permission.

cor repo list --remote ssh://HOST:8787
cor remote add ssh://HOST:8787/my-game
cor work

Remote discovery shows only repositories your authenticated key can access. Interactive setup at a bare server address asks which repository to use when several are available. A bare URL continues to select default for existing projects and scripts. Use a separate workspace folder for each repository.

team

cor team
cor team --web
cor team --json
cor team --before 100
cor team --output ../team.html

List people and recent accepted changes. --web opens a private, offline dashboard at .laplace/team.html; run again to refresh. --output saves a new HTML file without opening it. It must be outside the synced project or inside .laplace. Both HTML options are incompatible with --json.

The dashboard groups keys, filters people and sessions, and reveals file previews and review commands. Counts include accepted packages since accounting was enabled, including work outside sessions. Rejected packages and retries do not inflate totals. Each page contains up to 50 packages (at most 1 MiB), eight path previews per package, and 100 recent sessions. Older activity uses --before; full session changes use session show.

cor team rename alice "Alice Chen"
cor team rename alice "Alice Chen" --data /srv/corotation

Names are display metadata. SSH keys remain the identity for ownership and audit records. Revoked keys retain their history; grouping two keys does not share session ownership between them.

work

cor work

watch is an alias for work. Press Ctrl+C to stop. A configured worker retries when current is unavailable, including at startup.

remote

cor remote add YOUR_SERVER:8787
cor remote add studio ssh://YOUR_HOST:8787
cor remote list
cor remote use studio
cor remote remove studio

remote add accepts URL or NAME URL. The default name is current. Use --name NAME to name a single-URL form, --local to save only on this machine, or --offline to skip the initial connection. Omit the address in a terminal for guided setup.

Addresses use SSH on port 8787 unless another port is written. URLs cannot contain usernames, passwords, query parameters, or fragments. An optional single path selects a named repository. Host verification and identity are separate from the shareable address. cor remote alone lists remotes.

status and sync

cor status
cor status --json
cor sync

status is offline and read-only. It reports the worker lock, received sequence, pending package, interrupted apply state, and conflicts. It does not confirm the server’s live health.

sync performs one immediate exchange using saved settings. It accepts --remote and --workers. Stop the workspace’s worker first.

Publication checks and holds

cor checks init --preset auto
cor checks trust
cor check
cor check --fresh
cor checks
cor checks --watch --json
cor checks retry
cor hold
cor resume

Presets: auto, assets, node, threejs, rust. Checks run inside work, sync, and local conflict resolution. check runs without publishing. check, sync, and resolve exit 2 when publication checks block the change. checks retry invalidates local and configured server caches; check --fresh invalidates only local caches. Read the checks guide for configuration and incremental behavior.

hold prevents new publications while receiving other changes. An already submitted package can finish. resume restarts automatic publication; the hold survives worker restarts.

conflicts and resolve

cor conflicts
cor conflicts --watch --json
cor conflicts --check
cor resolve --take local
cor resolve --take current

--watch emits the initial conflict state and later changes. --check exits with code 2 when conflicts exist; it cannot be combined with --watch.

resolve requires --take local or --take current, accepts --remote and --workers, and acts on all active conflict packages. Stop the worker and inspect the full scope first. See the repair guide.

baselines, baseline, and export

cor baselines
cor baselines --before SEQUENCE
cor export --hash BASELINE_HASH --output ../recovered-game

baselines lists up to 100 remote references, newest first. export requires a new output directory. Both use the selected remote and accept --remote and --workers through the shared connection options.

cor baseline

baseline is a local server maintenance command. It accepts --data PATH, defaults to .laplace/current, and requires current to be stopped.

install

cor install

session

cor session start "Feature name"
cor session
cor session end
cor session retry
cor session list --json
cor session show SESSION_ID --json
cor session show SESSION_ID --output ../review
cor session hooks add NAME --on start -- COMMAND ARGUMENTS
cor session hooks add NAME --on end --timeout-seconds 600 -- COMMAND ARGUMENTS
cor session hooks
cor session hooks remove NAME

Start/end commands work alongside cor work. One session is open per workspace; it survives worker restarts. Changes keep syncing throughout. Start hooks gate new publication; end hooks run after a flush and their edits are flushed before closure. Failed transitions remain recoverable with retry. See sessions and hooks for ordering, context, review formats, and feature flags.

session alone shows offline local state. show defaults to the most recent local session ID. list --before NUMBER and show --after SEQUENCE paginate remote history. --output exports all packages into a new folder and cannot be combined with --after. Connection overrides go before the subcommand: cor session --remote NAME list.

Hooks accept argv after --, run natively from the project root, and time out after 300 seconds by default (1–3600 allowed). They are configured privately in .laplace/session-hooks.json and pinned for each session. .laplace/session.json is local progress; .laplace/session-request.json is the durable command intent; .laplace/identity.json stores the author and workspace ID. Hook contexts live in .laplace/sessions/SESSION_ID/. None of these files synchronize.

Configuration files

install --checks auto also configures publication checks. Detected projects are offered checks during interactive installation. corotation.json includes the shared checks policy; .laplace/checks-trust.json pins local approval. checks.laplace.json projects the private .laplace/checks-report.json. status --json includes validation and hold state.

Exit codes

Successful commands exit with 0. Runtime or setup errors exit with 1. Session transitions exit with 2 when a hook, check, hold, or conflict needs repair. conflicts --check exits with 2 when conflicts exist; command-line argument parsing errors can also use 2. A successful sync can still report a rejected package, so inspect its conflict statistics or run conflicts --check in automation.

SSH agent configuration

cor install --ssh-agent /path/to/agent.sock

For 1Password and other SSH agents, this saves a private, per-user socket setting in ~/.config/laplace/client.json. It applies to all projects without changing the system SSH environment or copying keys. LAPLACE_SSH_AGENT overrides it; without a saved setting, Corotation uses SSH_AUTH_SOCK.

jobs

cor jobs
cor jobs add release
cor jobs enable release
cor jobs run release
cor jobs logs release --follow
cor jobs retry 42
cor jobs artifacts 42
cor jobs disable release
cor jobs runners

add offers guided setup, or accepts --script PATH, --targets PLATFORM,PLATFORM, and --quiet DURATION. logs --run ID selects an exact run. artifacts --output PATH downloads outside the synchronized project. runners --revoke FINGERPRINT revokes an enrolled worker. Job commands infer the project's remote; use --remote to override it. See Jobs & runners for configuration and execution semantics.

runner

cor runner
cor runner settings
cor runner stop

Initial setup asks how to execute trusted scripts and starts a runner at login. --native explicitly selects host execution, while --image IMAGE uses a prepared Docker image. --foreground runs in the terminal; --once claims at most one task and exits. --name NAME, --target LABEL, and --jobs NAME,NAME update saved runner defaults. Use --remote to choose another configured repository. Each runner has one execution slot.

Saved identities

cor login
cor login --renew
cor logout
cor devices
cor devices revoke FINGERPRINT

Login remembers a separate repository-scoped SSH device key. Repeated login verifies the saved identity without your SSH agent; renewal explicitly requests your personal identity. An explicit --identity overrides saved-key selection for other commands. Logout revokes this device on current. Device management accepts --remote NAME and --json.