CLI reference
Every command and flag of syntic, as printed by syntic --help for version 0.1.0.
syntic [flags] [prompt] interactive session (or a one-shot run with -p)
syntic <command> [args] manage sign-in, settings, MCP, plugins, background runs, updatesFlags can go before or after the prompt. A prompt with spaces in it (in quotes) is always a prompt. A bare word that looks like a command Syntic Code does not have, such as syntic install or syntic plugins, stops with a short error naming the right command; the model never sees it.
Commands
| Command | Description | Example |
|---|---|---|
syntic | Start an interactive session in the current folder. | syntic |
syntic "<prompt>" | Start an interactive session with a first message. | syntic "why is the build slow?" |
syntic -p "<prompt>" | Run one task, print the result, exit. | syntic -p "summarize README.md" |
syntic login, syntic auth login | Sign in through the browser. --subscription signs in with your Syntic subscription. | syntic auth login |
syntic auth status | Show sign-in state. --json for one JSON object. Exit code 0 when signed in, 1 when not. | syntic auth status --json |
syntic auth logout | Remove stored credentials. | syntic auth logout |
syntic setup-token | Store a long-lived token without a browser. Reads it from standard input or a hidden prompt. | echo "$TOKEN" | syntic setup-token |
syntic doctor | Print a read-only check of folders, settings, model, credentials, install and policy. | syntic doctor |
syntic config <get|set|add|remove|list> | Read and change settings without starting a session. | syntic config set theme light |
syntic mcp <…> | Manage MCP servers (see below). | syntic mcp list |
syntic plugin <…> | Manage plugins and marketplaces (see below). | syntic plugin list |
syntic mod <list|enable|disable> | Manage mods. | syntic mod enable turn-clock |
syntic agents | Full-screen dashboard of background sessions across projects. --json, --cwd <path>, --list (agent definitions). | syntic agents --json |
syntic sessions (also ps) | List background sessions. --prune [--older-than <days>] removes finished ones. | syntic ps |
syntic logs <id> | Print a background session’s output; -f follows it. | syntic logs 08e1 -f |
syntic attach <id> | Open a background session in the interactive screen. | syntic attach 08e1 |
syntic stop <id> | Stop a running background session. | syntic stop 08e1 |
syntic respawn [id] | Continue an interrupted, failed, stopped or waiting background session. --interrupted does all interrupted ones. | syntic respawn --interrupted |
syntic rm <id> | Remove a finished background session and its log. | syntic rm 08e1 |
syntic update | Update to the newest release. --check, --channel stable|latest, --rollback, --allow-downgrade, --manifest-url <url>. | syntic update --check |
syntic completion <shell> | Print a completion script for bash, zsh, fish, powershell or elvish. | syntic completion zsh > ~/.zfunc/_syntic |
syntic auto-mode reset | Remove your custom auto mode rules (-y skips the question). | syntic auto-mode reset -y |
syntic project purge [path] | Delete what Syntic stored about a project: sessions, MCP approvals, folder trust. -y, --dry-run. | syntic project purge --dry-run |
syntic help [command] | Print help. syntic <command> --help works too. | syntic help mcp |
Flags
Starting and resuming
| Flag | Description | Example |
|---|---|---|
-c, --continue | Resume the latest session in this folder. | syntic -c |
-r, --resume [id] | Resume a session by id or name; with no id in a terminal, the session picker opens inside the app (from a script, or with -p, --all-projects or --fork-session, the sessions are listed instead). | syntic --resume billing-bug |
--all-projects | With --resume and no id: list sessions from every folder. | syntic --resume --all-projects |
--fork-session | When resuming, continue in a new session and leave the original as it was. | syntic -c --fork-session |
--resume-session-at <message> | When resuming, continue from an earlier message (id, unique prefix, or a count N). | syntic --resume abc --resume-session-at 12 |
--rewind-files <message-id> | With --resume <id>: restore that session’s files to before the message, then exit. | syntic --resume abc --rewind-files 7f2e… |
--from-pr <number or URL> | Resume the session that opened this pull request. | syntic --from-pr 482 |
--session-id <uuid> | Use this session id. | syntic -p "hi" --session-id 1111… |
-n, --name <name> | Name the session (shown in the resume list). | syntic -n "release prep" |
--no-session-persistence | Save nothing for this session. | syntic -p "…" --no-session-persistence |
-w, --worktree [name] | Start in a git worktree under .syntic/worktrees/ (a pull request URL, #123 or !45 checks that out). | syntic -w '#482' |
--tmux | With --worktree: run inside a tmux session named after the worktree. | syntic -w api-fix --tmux |
--add-dir <path> | Also work in this folder (repeatable). | syntic --add-dir ../shared |
--handle-uri <uri> | Open a syntic-cli:// link (used by your operating system). | |
--init | Run Setup hooks (trigger init) before the session. | syntic --init |
--init-only | Run Setup hooks (trigger init) and exit. | syntic --init-only |
--maintenance | Run Setup hooks with trigger maintenance before the session. | syntic --maintenance |
One-shot and scripted runs
| Flag | Description | Example |
|---|---|---|
-p, --print | Run one task without the interactive screen and exit. Piped input is added to the prompt. | cat log.txt | syntic -p "what failed?" |
--bg (also --background) | Run as a background session that outlives the terminal (implies -p). | syntic --bg "migrate the tests" |
--output-format <format> | text (default), json, or stream-json (needs --verbose). | syntic -p "…" --output-format json |
--input-format <format> | text (default) or stream-json from standard input. | syntic -p --input-format stream-json |
--json-schema <schema or file> | Require a JSON answer matching this schema. | syntic -p "…" --json-schema schema.json |
--include-partial-messages | stream-json: stream text and reasoning as it arrives. | |
--include-hook-events | stream-json: report each hook that runs. | |
--replay-user-messages | stream-json: echo each user message. | |
--forward-subagent-text | stream-json: include subagents’ text and reasoning. | |
--max-turns <n> | Stop after n agent turns (0 = no limit). | syntic -p "…" --max-turns 10 |
--permission-prompts <host|none> | Who answers permission questions in a -p run: host (default) or none, which refuses every question at once so the run never waits. | syntic -p "…" --permission-prompts none |
--max-budget-usd <amount> | Stop when the run’s estimated cost passes this amount. | syntic -p "…" --max-budget-usd 2 |
--task-budget <amount> | A per-task cost cap, alongside --max-budget-usd. | |
--exclude-dynamic-system-prompt-sections | Keep machine-specific details out of the system prompt so it caches across machines. | |
--system-prompt-snapshot <on|off> | off rebuilds the system prompt every turn. | |
--dump-system-prompt | Print the system prompt your settings produce, and exit. | syntic --dump-system-prompt |
Model and reasoning
| Flag | Description | Example |
|---|---|---|
--model <name> | Model for this run. | syntic --model "Syntic Code Fast" |
--small-model <name> | Model for background helper tasks. | |
--fallback-model <name> | Model to use when the main one is unavailable. | |
--effort <level> | low, medium, high, xhigh or max. | syntic --effort high |
--max-thinking-tokens <n> (also --thinking) | Reasoning budget (0 turns reasoning off). | |
--api-base <url> | API base URL (Syntic hosts only). | |
--advisor <model> | Turn the Advisor tool on for this session, on this model (not saved). | syntic --advisor "Syntic Code" |
--autocompact <auto|size> | Auto-compact window for this session only: auto (the model’s own window) or a size such as 200k or 1m. | syntic --autocompact 200k |
Instructions and agents
| Flag | Description | Example |
|---|---|---|
--system-prompt <text> | Replace the built-in system prompt. | |
--system-prompt-file <file> | The same, from a file (the inline flag wins). | syntic -p "…" --system-prompt-file prompt.md |
--append-system-prompt <text> | Add to the end of the system prompt. | syntic --append-system-prompt "Answer in German." |
--append-system-prompt-file <file> | The same, from a file. | |
--append-subagent-system-prompt <text> | Add to every subagent’s system prompt. | |
--append-subagent-system-prompt-file <file> | The same, from a file. | |
--output-style <style> | Output style for this run. | syntic --output-style Concise |
--agent <name> | Run the main session as this custom agent. | syntic --agent reviewer |
--agents <json or file> | Extra agent definitions for this run. | syntic --agents agents.json |
Permissions and tools
| Flag | Description | Example |
|---|---|---|
--permission-mode <mode> | default, acceptEdits (shown as auto-edit), auto, plan, bypassPermissions (bypass) or dontAsk (shown as don’t-ask). | syntic --permission-mode plan |
--dangerously-skip-permissions | Start in bypass mode. Deny rules still apply. | |
--allow-dangerously-skip-permissions | Let Shift+Tab reach bypass mode without starting in it. | |
--allowed-tools <list> (also --allowedTools) | Rules that run without asking. | --allowed-tools "Bash(npm test:*),Read" |
--disallowed-tools <list> (also --disallowedTools) | Rules that are refused (win over allowed). | --disallowed-tools "WebFetch" |
--tools <list> | Offer only these built-in tools ("" none, default all). | --tools "Read,Grep,Glob" |
--permission-prompt-tool <name> (also --permissionPromptTool) | A tool that answers approvals the rules do not settle (headless). | --permission-prompt-tool mcp__auth__approve |
--disable-slash-commands | Treat lines starting with / as plain text. | |
--bare | Minimal session for scripts (no settings hooks, plugins, skill discovery, auto memory). | syntic -p "…" --bare |
--safe-mode | Troubleshooting start: memory files, plugins, skills, hooks and MCP servers off. | syntic --safe-mode |
--restricted | Locked-down session: no shell, code or web-fetch tools; file tools stay in this folder. | syntic --restricted |
Settings, MCP and plugins
| Flag | Description | Example |
|---|---|---|
--settings <file or json> | Layer extra settings for this run. | --settings '{"verbose":true}' |
--setting-sources <list> | Read only these settings files: user, project, local, policy. | --setting-sources user |
--mcp-config <file or json> | Add MCP servers for this run (repeatable). | --mcp-config servers.json |
--strict-mcp-config | Use only the --mcp-config servers. | |
--channels <servers> | Let these MCP servers push messages into the session (Channels reference). | --channels slackbridge |
--plugin <plugin@marketplace> | Install a plugin before the run without asking (repeatable). | --plugin formatter@acme |
--plugin-scope <scope> | Where --plugin records the install: user (default), project, local. | |
--plugin-dir <folder or zip> | Use a plugin for this run only (repeatable). | --plugin-dir ./my-plugin |
--plugin-url <https url> | Download a plugin zip for this run only (repeatable). |
Display
| Flag | Description | Example |
|---|---|---|
--theme <name> | Theme for this run. | syntic --theme light |
--inline | Draw in the terminal’s normal screen (default). | |
--fullscreen | Use the full-screen view. | syntic --fullscreen |
--screen-reader (also --ax-screen-reader) | Screen reader mode. | |
--no-color | No color (same as NO_COLOR=1). | |
--ide | Connect at startup to the one running editor that has this folder open, even outside its terminal. | syntic --ide |
-v, --verbose | More detail in output. |
Sign-in
| Flag | Description |
|---|---|
--login | Sign in through the browser. |
--subscription | Sign in with your Syntic subscription (implies --login when alone). |
Debugging
| Flag | Description | Example |
|---|---|---|
--debug [targets] | Debug logging, optionally limited to areas. | syntic --debug api,hooks |
--debug-file <file> | Also write logs to a file (use with --debug). | syntic --debug --debug-file /tmp/syntic.log |
--debug-to-stderr | Logs to standard error (already the default). | |
--mcp-debug | Debug logging for MCP servers only. | |
-h, --help | Print help. | |
-V, --version | Print the version. | syntic -V |
-v means --verbose, not version. Use -V or --version.
syntic config
| Command | Description | Example |
|---|---|---|
syntic config get <key> | Print a value as JSON (non-zero exit if unset). | syntic config get model |
syntic config set <key> <value> | Set a value (JSON is understood). | syntic config set vimMode true |
syntic config add <key> <values…> | Append to a list, skipping duplicates. | syntic config add companyAnnouncements "Hi" |
syntic config remove <key> [values…] | Delete a key, or values from a list. | syntic config remove theme |
syntic config list | Print the settings file. | syntic config list --project |
Scope flags: -g/--global (default, ~/.syntic/settings.json), --project (.syntic/settings.json), --local (.syntic/settings.local.json).
syntic mcp
| Command | Description | Example |
|---|---|---|
syntic mcp add <name> <command-or-url> [args…] | Add a server. -t/--transport stdio|sse|http, -e/--env KEY=VALUE, --header "Name: Value", -s/--scope local|project|user. | syntic mcp add docs https://mcp.example.com/mcp -t http |
syntic mcp add-json <name> <json> | Add a server from a JSON definition (-s scope). | syntic mcp add-json fs '{"command":"npx","args":["-y","@example/fs"]}' |
syntic mcp list | List servers. -s scope, --json, --check (start each local server to test it). | syntic mcp list --check |
syntic mcp get <name> | Show one server, secrets masked. -s, --json. | syntic mcp get docs |
syntic mcp remove <name> | Remove a server (-s when it exists in several scopes). | syntic mcp remove docs |
syntic mcp login <name> | Sign in to a remote server. --no-browser prints the address. | syntic mcp login tracker |
syntic mcp logout <name> | Forget a server’s sign-in. | |
syntic mcp reset-project-choices | Forget this project’s approve/reject answers for its servers. | |
syntic mcp serve | Run Syntic Code’s tools as an MCP server over standard input and output. |
syntic plugin
Install, update and manage plugins and marketplaces from your shell. Every subcommand accepts --json.
| Command | Description | Example |
|---|---|---|
syntic plugin install <plugin@marketplace> | Install a plugin. | syntic plugin install formatter@acme --scope project |
syntic plugin list | Installed plugins (--available for what marketplaces offer). | syntic plugin list --available |
syntic plugin marketplace add <source> | Save a marketplace. | syntic plugin marketplace add acme/plugins |
The full list of subcommands and flags, including enable, disable, update, validate, eval, init and tag, is on Plugin commands.
syntic mod
| Command | Description |
|---|---|
syntic mod list | Installed mods, whether each is on, and what each may do. |
syntic mod enable <name> | Switch on and grant the permissions its mod.json asks for. |
syntic mod disable <name> | Switch off and drop its permissions. |
Exit codes
| Code | Meaning |
|---|---|
0 | Success. |
1 | Failure (API error, not signed in, budget reached, schema mismatch). auth status: not signed in. |
2 | Bad usage: unknown flag, bad value, unknown command. |
3 | syntic update --check: a newer release exists. |
4 | This version is below the minimum supported version. |