Synsci CLI commands reference

This page lists every subcommand that ships with synsc, what it does, and the most useful flags. The bare synsc (no arguments) drops you into the TUI in the build agent and the general research mode.

Connection

`synsc connect`

Manage the Bearer token connection between your CLI and the dashboard at cli.syntheticsciences.ai.

Subcommand	Purpose
`synsc connect login`	Run the device-flow OAuth login. Opens your browser and stores the resulting Bearer token in OS keychain.
`synsc connect status`	Show your account email, synced credentials, active mode, and credit balance.
`synsc connect logout`	Invalidate the local Bearer token.

Sessions

`synsc web` (recommended)

Boot a local server and open the browser UI. The recommended day-to-day interface. See Web UI for the full feature set.

synsc web
synsc web --mode chemistry
synsc web --port 5555
synsc web --agent plan
synsc web --host 0.0.0.0    # expose to LAN, use carefully

Flags:

--mode <name> for the research mode (research, physics, chemistry, biology, flywheel).
--agent <build|plan> for the agent (default: build).
--port <n> to bind on 127.0.0.1 (default: 4444).
--host <addr> to override the bind interface (default: 127.0.0.1).
--no-open to skip auto-opening the browser.

`synsc` (no args, TUI mode)

Start a TUI session. Useful when you want everything in the terminal.

synsc
synsc --mode biology
synsc --agent plan
synsc --project research-fork

Flags:

--mode <name> for the research mode.
--agent <build|plan> for the agent.
--project <name> to tag the session for dashboard rollups.
--cwd <path> to start with a specific working directory.

`synsc run`

One-shot run. Sends the prompt, lets the agent work to completion, and exits.

synsc run --mode ml "Refactor utils/log.ts to use structured logging"
synsc run --mode chemistry "Set up a DFT optimization for this CIF file"
synsc run --agent plan "Summarize the architecture of src/"

Useful for git hooks, CI, and shell pipelines.

`synsc session`

Inspect and manage past sessions stored on the dashboard.

Subcommand	Purpose
`synsc session list`	List recent sessions.
`synsc session show <id>`	Print the prompts and assistant messages for a session.
`synsc session resume <id>`	Continue a prior session in the TUI.

Research modes

`synsc mode`

Manage research modes. See research, physics, chemistry, biology, and flywheel for what each mode covers.

Subcommand	Purpose
`synsc mode list`	List available research modes on this install.
`synsc mode show`	Show the active mode for the current directory.
`synsc mode set <name>`	Set the default mode for the current working directory.

Stats

`synsc stats`

Show credit usage by session, mode, and time window.

synsc stats              # cumulative
synsc stats --since 7d   # last 7 days
synsc stats --json       # machine-readable

Agent management

`synsc agent`

Manage agent profiles. Defaults, per-project overrides, and custom profiles.

Subcommand	Purpose
`synsc agent list`	Show available agent profiles.
`synsc agent set-default <name>`	Set your default agent.
`synsc agent show <name>`	Print the full configuration for an agent.

MCP

`synsc mcp`

Configure Model Context Protocol servers. Synsci CLI can act as both an MCP host (consuming tools from external MCP servers like Thesis) and an MCP server (exposing its own tools to other hosts).

Subcommand	Purpose
`synsc mcp list`	List configured MCP servers.
`synsc mcp add <name> --url <url>`	Register an MCP server.
`synsc mcp remove <name>`	Unregister an MCP server.
`synsc mcp test <name>`	Test connectivity to a registered MCP server.

To connect Synsci CLI to your Thesis workspace as an MCP host:

synsc mcp add thesis --url https://thesis.syntheticsciences.ai/mcp-server

See Connect Synsci CLI to Thesis for the full integration walkthrough.

GitHub and PR helpers

`synsc github`

GitHub helpers that compose with gh and the Synsci agent.

Subcommand	Purpose
`synsc github review <pr>`	Open a PR and ask the agent to review it.
`synsc github resolve <issue>`	Open an issue and ask the agent to plan a fix.

`synsc pr`

PR-focused workflows.

Subcommand	Purpose
`synsc pr open`	Create a PR from the current branch with an agent-generated body.
`synsc pr update <pr>`	Update a PR description after new commits.

Sessions: export and import

`synsc export`

Export a session as a JSON document for sharing or archiving.

synsc export <session-id> --out session.json

`synsc import`

Import a session JSON back into your account.

synsc import session.json

Useful for handing off context to a teammate or restoring a session on a new machine.

Distribution and lifecycle

`synsc upgrade`

Upgrade to the latest published version. Detects how you installed (npm, Homebrew, or direct binary) and runs the matching update flow.

synsc upgrade
synsc upgrade --version 1.2.0   # pin to a specific version

`synsc uninstall`

Remove the CLI and clear local config.

synsc uninstall

The dashboard account, credentials, and session history are unaffected.

`synsc generate`

Generate boilerplate. The exact templates depend on the version, but typical generators include Synsci CLI plugin scaffolds and project templates.

synsc generate --help

Server modes

`synsc serve`

Run the CLI as a long-lived backend server, exposing an HTTP API. Useful when you want a remote agent endpoint that other tools can call.

synsc serve --port 4444

`synsc acp`

Speak the Agent Communication Protocol over stdio. This is what the desktop app and IDE plugins use to talk to the agent. You usually don’t run this directly.

Slash commands inside a session

Slash commands work inside any session: web UI, TUI, or desktop.

Slash command	Action
`/mode <name>`	Switch research mode.
`/agent <name>`	Switch agents (also via the toggle in web/desktop, or `Tab` in TUI).
`/clear`	Clear the conversation context.
`/save`	Save the session to your dashboard.
`/export`	Export the conversation to a markdown file.
`/help`	Show available slash commands.

Environment variables

Useful env vars the CLI reads at startup:

Variable	Purpose
`SYNSC_DASHBOARD_URL`	Override the dashboard URL (default `https://cli.syntheticsciences.ai`).
`SYNSC_DEFAULT_MODE`	Default research mode.
`SYNSC_DEFAULT_AGENT`	Default agent (`build` or `plan`).

Provider keys for credentials (HF, W&B, Modal, Lambda, AWS, GCP) come from the dashboard sync. See Credentials.

What’s next

Connect Thesis via MCP. Wire Synsci CLI to your Thesis workspace.
Security model. Credential boundary, output redaction, and per-user isolation.

Start

Agents

Research modes

Operations

MCP

Reference

Connection

`synsc connect`

Sessions

`synsc web` (recommended)

`synsc` (no args, TUI mode)

`synsc run`

`synsc session`

Research modes

`synsc mode`

Stats

`synsc stats`

Agent management

`synsc agent`

MCP

`synsc mcp`

GitHub and PR helpers

`synsc github`

`synsc pr`

Sessions: export and import

`synsc export`

`synsc import`

Distribution and lifecycle

`synsc upgrade`

`synsc uninstall`

`synsc generate`

Server modes

`synsc serve`

`synsc acp`

Slash commands inside a session

Environment variables

What’s next

Start

Agents

Research modes

Operations

MCP

Reference

​Connection

​synsc connect

​Sessions

​synsc web (recommended)

​synsc (no args, TUI mode)

​synsc run

​synsc session

​Research modes

​synsc mode

​Stats

​synsc stats

​Agent management

​synsc agent

​MCP

​synsc mcp

​GitHub and PR helpers

​synsc github

​synsc pr

​Sessions: export and import

​synsc export

​synsc import

​Distribution and lifecycle

​synsc upgrade

​synsc uninstall

​synsc generate

​Server modes

​synsc serve

​synsc acp

​Slash commands inside a session

​Environment variables

​What’s next

Connection

`synsc connect`

Sessions

`synsc web` (recommended)

`synsc` (no args, TUI mode)

`synsc run`

`synsc session`

Research modes

`synsc mode`

Stats

`synsc stats`

Agent management

`synsc agent`

MCP

`synsc mcp`

GitHub and PR helpers

`synsc github`

`synsc pr`

Sessions: export and import

`synsc export`

`synsc import`

Distribution and lifecycle

`synsc upgrade`

`synsc uninstall`

`synsc generate`

Server modes

`synsc serve`

`synsc acp`

Slash commands inside a session

Environment variables

What’s next