CLI commands

Commands for setup, Rules, events, accounts and recovery.

For signup with your agent, account claiming and first-Rule verification, use the Quickstart and its CLI instructions. The commands below cover installation, Rules, events and account management. Check which CLI version is installed:

synkro --version
synkro --help
synkro help
synkro COMMAND --help

Replace COMMAND with a command name. -h also prints help. For a subcommand, run synkro help account usage.

For bug reports and improvement suggestions, see Feedback. That guide covers submission examples, automatic diagnostics and saved-report retries.

Send feedback

synkro feedback

Submit a bug report or improvement suggestion through your signed-in account or approved agent connection. Use --title "Short summary" and --message "Steps, expected result and actual result"; --message - reads standard input. Add --json for a structured receipt. The command attaches available platform, account and diagnostic context automatically.

Optional --trace TRACE_ID, --session SESSION_ID and --verdict UUID select a known failure. Multiple selectors narrow the evidence together. The server limits evidence to the submitting agent installation.

synkro feedback status SUBMISSION_UUID

Check whether the saved report is pending or delivered. A delivered receipt includes its support issue identifier and URL. Accepts --json.

synkro feedback retry SUBMISSION_UUID

Resend the saved report with the original ID, message and diagnostics. Use the original account, installation and service. Accepts --json. Check status before retrying; do not create duplicate reports while delivery is pending.

Signup and setup with your agent

synkro onboard

Starts registration on your behalf, connects the agent after you claim the account and approve the connection, and verifies its first Rule. Every subcommand accepts --json for structured progress and the next step. You review and approve the proposed Rule separately.

For the current sandbox signup, set this for every setup command and resumed session:

export SYNKRO_WEB_AUTH_URL="https://app.sandbox.synkro.sh"

Use test cards only. Keep an existing production installation separate. See the Quickstart for the human approval steps.

synkro onboard start

Adds your email to the waitlist with --email EMAIL. New accounts wait for Synkro staff approval, then you verify your email and claim the account. Optional --organization NAME proposes a name; omit it to choose during account claiming. Use resume to continue the saved application instead of submitting again.

Agents follow the signup instructions. You can also request access on the website. Both use the same waitlist.

synkro onboard status

Checks the saved signup request once. It does not wait or create another signup.

synkro onboard resume

Continues saved signup, agent connection or verification. --wait-seconds SECONDS waits for staff approval or account claiming for up to 300 seconds; the default is zero, which checks once. Keep the original service and installation directory. Existing connection credentials can be renewed without a new signup.

synkro onboard claim

Prepares or resumes a request to connect the agent to your account. --email EMAIL defaults to the saved signup email. You must open the returned verification link, claim the account and approve the connection. Only then does the CLI collect a limited credential for the agent; there is no connection code to copy.

Use --harness HARNESS to identify the agent and --name "My Codex" to give the connection a recognizable label. Use separate installation directories for independently revocable connections; agents sharing credentials share one connection.

Use --new-link to replace an expired verification link while keeping the same account and saved signup.

Collection resumes after an interrupted request using the retained result. If the service confirms an expired or rejected attempt can safely be replaced, the CLI returns a renewed connection link for your approval. An uncertain completion preserves saved state and gives support guidance; it does not repeat a one-time exchange or create another account.

synkro onboard verify

Reads existing Rule checks and a recorded agent action to verify setup. Run without options to resume the saved verification.

Completion requires passing checks, published policy and a recorded action under that policy. The connected agent uses this command to read its setup evidence. It can also use events and trace to investigate its own installation; organization-wide history requires a human sign-in.

The recorded action is the final decision for the whole tool call. action.rule_matches lists the requested Rule's recorded match events, their kind (deterministic or semantic) and their mode. Several Rules can share one verdict ID. Read their match events to see which ones contributed. A fix Rule refuses the action as block and supplies correction guidance. The corrected attempt is recorded as a separate action.

Find Rule suggestions from PRs

synkro discover

Collects accepted review feedback from merged PRs. Public scans use your authenticated GitHub CLI (gh); --connected uses your GitHub connection for private repositories. Your agent maps the feedback to the current code and saves Rule suggestions.

A supported PR-creation hook supplies an incremental start command with a stable --request-id. Retry that same command to resume, not to create another window. start reads the scan's current phase, including a completed receipt. See automatic PR follow-ups for supported tools and the manual path.

All subcommands print JSON. --json is also accepted. Errors and retry IDs go to stderr. Use the same signed-in installation and initialized project throughout the scan. Project Rules must already be published by an agent hook.

Add --connected to start for private repositories. collect-scan uses the saved access method; it needs no extra flag.

For completion, examined_evidence_ids must contain exactly the IDs in the scan's admitted list, once each. Do not include deduplicated IDs; use [] when no evidence was admitted. revalidations must cover exactly findings_for_revalidation, once each, even when admitted is empty. Use [] when no findings require revalidation. These lists have different purposes.

For another findings page, pass the last returned ID to --after. An empty page ends the list. Results are scoped to your organization, installation, project and source repository. propose returns finding, skill and instructions. Your agent follows those instructions; the CLI does not invoke the agent or activate a Rule. Dismissed, missing or inaccessible findings return an error, not a proposal.

start, submit, complete and dismiss accept --request-id UUID. If a request's result is unknown, reuse its printed UUID with identical input or read the saved record first. Do not reuse an ID with different input. Incomplete collection cannot be submitted as a completed scan.

Dismissal requires a nonempty reason. Normal lists and later reassessments skip dismissed findings. Read one by ID or pass --include-dismissed to see it again. Repeating dismissal keeps the original reason, actor and time.

Discovery creates suggestions, not active Rules. It does not review the current PR or approve a merge. The Rules guide shows how to ask your agent to use it.

Install, update, and remove

synkro install

Signs in if needed and connects detected agents to Synkro's hosted service. Existing service settings are preserved. Use --daemon-url for an address supplied by your administrator.

If your saved session has expired, installation first tries to refresh it. It asks you to sign in if the refresh fails or takes longer than 10 seconds. --force always asks you to sign in again.

For device sign-in, open the printed link or visit https://app.sandbox.synkro.sh/device and enter the short code.

synkro update

Updates installed components to match this CLI. It does not upgrade the CLI executable.

Synkro can notify your agent when a newer CLI version is available. The agent should tell you and ask for approval before upgrading. If you decline, it continues your work without asking again for that version. Release checks run separately from enforcement; an unavailable release service does not interrupt your tool calls.

To check explicitly, run synkro update --check. This reports availability for your release channel and leaves the installed CLI and integrations unchanged.

For a Homebrew CLI upgrade, run:

brew update
brew upgrade synkro-sh/tap/synkro
synkro update --yes

synkro uninstall

Removes Synkro's agent integrations and managed hook executable. Unrelated settings, the Homebrew package and recorded history are preserved. It has no options beyond --help.

Project Rules

Run these commands inside a project, or use --path DIR to select the project containing another directory.

synkro init

Creates synkro.toml and, by default, an empty local Rule package at .synkro/policy. It copies declarations from your user-level Rule blueprint. It does not create synkro.lock or overwrite an existing project.

synkro lock

Resolves the declared Rule packages and writes synkro.lock. Use --path DIR to select another project. This option also works with synkro lock update.

An invalid Rule fails the command with its file and parser error. The existing lock stays unchanged. Fix the file and rerun the command; an invalid Rule is not silently left out.

synkro lock update [DEPENDENCY]

Refreshes one dependency alias, or all dependencies if no alias is given, then validates before replacing the lock. Full commit pins advance to remote HEAD; named refs resolve again without changing their names; local path packages use their current contents. Use --path DIR to select another project.

synkro lock update
synkro lock update my-rules --path /path/to/project

See Rules before changing project dependencies.

synkro approve mcp SERVER [TOOL]

Approve an exact MCP tool, or every tool on a server when TOOL is omitted:

synkro approve mcp linear-server
synkro approve mcp github read_issue
synkro approvals mcp
synkro approvals mcp github read_issue
synkro revoke mcp github read_issue
synkro revoke mcp linear-server

synkro approvals mcp [SERVER [TOOL]] lists effective approvals and denials, including their project or package source. synkro revoke mcp SERVER [TOOL] removes the project declaration; if a package default or project wildcard still approves the scope, it writes approved = false instead. Unreadable package defaults are reported; revocation still writes an explicit project denial. Listing reports unknown coordinates rather than declaring them unapproved when unreadable defaults could cover them.

All three commands accept --path DIR and --package ALIAS. Edits default to that project's synkro.toml. An explicit package alias selects approve-only defaults in its synkro-package.toml; Git dependencies are read-only here, so edit their source repository. Listing uses locked Git content without fetching.

[[approvals.mcp]]
server = "github"
tool = "read_issue"
approved = true

The resolution order is project exact, project server wildcard (tool = "*"), any package default, then unapproved. Only the project can set approved = false. Other rules and controls still apply to approved tools.

An empty package section falls back to its existing approvals.toml. A nonempty section wins, and commands report that the file is ignored. On the first --package edit, fallback entries move into the manifest and the file is removed, with private backups. A last-entry revoke refuses to reactivate an ignored file; remove that file first. Repeated approvals are otherwise no-ops.

Upgrade both CLI and daemon before declaring manifest approvals. The next hook publishes the change; synkro lock records its digest. Existing package fallback files continue to work, and manifest schema versions stay unchanged. When your agent needs access, it should explain the exact server, tool, project and reason, then wait for your approval before running the command. Approving one tool does not approve the whole server. After the change, inspect the next action with synkro events to confirm the published policy was used. No separate access-request inbox is involved.

Listing shows source packages, including locally available Git dependencies at their locked commits. Missing or incomplete packages are reported individually; valid approval declarations from other packages remain visible. A tool filter also shows whole-server approvals that cover that tool.

Revoking without a tool removes every approval for that server in the selected package. An exact-tool revoke cannot carve an exception out of a whole-server approval: revoke that server approval first and add the desired individual tools. Another declared package can still approve the same tool; listing makes that visible.

These approvals remove only the unapproved-MCP notice or refusal. Other policy rules, controls and consent still apply. Unapproved calls retain their per-call notice in observe mode and refusal in enforce mode. Approval scope is the project's published policy generation, not a separate per-user permission store.

An invalid approval-file edit retains the previous valid policy generation and its approvals. On first publication with no prior generation, invalid approval evidence is reported and only the approval gate fails open.

synkro check

Tests deterministic and semantic examples in the project's Rules. The report shows passes, failures, skipped examples, and errors.

A pending model result is reattached using the same decision key and request; it does not start another paid grade. check_grade_wait_timeout_ms bounds the whole wait (45 seconds by default), with check_grade_retry_delay_ms between pending-result replies (250 ms). Set these under [settings] or through their SYNKRO_ environment overrides. Other refusals remain errors. If the total wait expires, the result is still unknown: the accepted decision continues, and a new synkro check creates a new decision.

Service and status

synkro status

Shows service health, account access and agent-integration state. Use --json for structured output.

Check running, healthy and plugins for service and integration status. health.enforcement.state shows whether Rules are active or paused; health.components.semantic_judge reports semantic-check status.

synkro trace TRACE_ID

synkro trace TRACE_ID shows the timeline of one hook, including transport records, persisted spans, the session-service journal and diagnostics awaiting delivery. Use the 32-character trace ID from the hook notice; add --json for machine-readable output.

The health report has scope: process; project Rule counts are null with status: not_reported. Use synkro onboard verify --json to verify your onboarding Rule and recorded action.

The default view starts with the outcome, verdict (when recorded), CLI time and verdict-available offset. A compact waterfall uses offsets from hook start and highlights the two largest durations. Each journaled step shows its round trip, body time and outside-body wait. The invocation tree groups work by parent; --verbose expands the chronological evidence and each invocation's journal. Color is used only on a terminal and respects NO_COLOR.

Missing measurements render as unknown. Cross-host gaps are estimates (~); a negative gap is labeled clock skew, not negative latency. "Before session service" means unmeasured daemon/ingress time before root creation, not admission delay. Buckets partition the measured CLI interval using estimated placement of daemon and journal evidence; nested durations must not be added to that total. Loader time and final process teardown outside the CLI scope are not measured. Persisted spans are the primary timing source. The CLI scope and stage spans reconstruct client offsets; typed step spans reconstruct daemon durations and publication markers after a restart or in-memory buffer eviction. Recent receipts and timings supplement spans that have not been exported yet, with overlapping copies counted once. Reconstructed CLI offsets use same-process span timestamps, which the view identifies separately from monotonic receipts. If the CLI timing scope is unavailable even in stored spans, the human view explains that once and lists available daemon durations without offsets or bars. Without a complete CLI scope, it omits the bucket section and explains why. JSON retains the same schema and explicit nulls for these partial traces.

outputAvailableOffsetUs measures when the CLI finished writing its answer. postResponseDiagnosticsUs measures the remaining diagnostic work before the CLI scope ended. Neither is the server's verdictAvailableOffsetUs; that stays null when server evidence is unavailable. A five-second hook total alone does not mean the model took five seconds or that the verdict timed out.

CLI spans upload before transport receipts, in separate requests with independent retry backoff. A slow receipt write cannot hold a span acknowledgement or prevent the next hook from delivering spans. Hook uploads share the configured hook_diagnostics_timeout_ms budget; an explicit synkro trace retries delivery using trace_request_timeout_ms. synkro status also retries once now. Neither deadline means that an unacknowledged write failed to reach the server: queued records remain retryable by their IDs.

synkro status --json reports receipt and span upload failures separately in hookDiagnostics, including the last failure classification and next retry time. failedUploads and failedSpanUploads count consecutive failed or unacknowledged batches, not all past failures. Zero does not mean the queue is empty. pendingObservations, oldestQueuedAt and oldestQueuedAgeSecs show the backlog; the age fields are null when no readable records are queued. deliveryAttempt describes this status command's retry: idle, acknowledged, deferred, deadline_exceeded or failed. An acknowledged batch can leave other batches pending. acknowledgedObservations counts successful record acknowledgements since this local counter was created; an interrupted replay can count again.

Hooks mark a deferred upload as unknown and a failed upload as failed, not succeeded. Their final timing records stay queued for a later hook, status or trace call. There is no uploader running after the CLI exits. If the queue does not shrink after retries, check its failure classification and next retry time. It also reports cumulative evictedObservations, evictedSpans, rejectedObservations, and rejectedSpans. Queue bounds can discard undelivered evidence; these losses emit warnings, and a later successful upload does not erase their counters. Already-evicted spans cannot be reconstructed by synkro trace.

Trace JSON contract (version 1)

synkro trace TRACE_ID --json writes exactly one JSON document to stdout. Diagnostics go to stderr; server failures retain the document and exit nonzero. --verbose changes only human output. Fields use camelCase, durations use integer microseconds, timestamps use RFC3339, and absent measurements are null. Signed cross-host values retain clock skew for analysis.

Bucket IDs are cli_preparation, judge, step_body, journal_round_trip_or_wait, daemon_wait_or_unmeasured, judge_and_receipt_estimate, step_body_estimate, cli_decode_and_output, post_response_diagnostics, and transport_or_unattributed. No evidence for a category produces null; its absence must not be interpreted as zero cost. Consumers should use IDs, not display labels or note text, and tolerate added fields. Incompatible view-model changes increment schemaVersion.

Events

synkro events reads your organization's recorded actions and decisions.

Your signed-in CLI with a human login reads the organization's history. A human-claimed agent with active organization membership and synkro:evidence reads only its own installation's hooks and associated decisions, evaluations, matches and errors. Filters and pagination cannot expand that scope. Agent trace reads use the same ownership boundary; shared server spans, timings and journals are excluded and reported as scope_restricted. For setup, synkro onboard verify remains the check for first-Rule and action evidence.

Quote wildcard selectors so the shell does not expand them. Accepted time forms are MMDDYY, MMDD (this year), MMDDYY-HH:MM:SS, HH:MM:SS (today), YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS, and RFC3339. Times without an offset use --tz. For a local time that is ambiguous or does not exist because of daylight saving changes, use RFC3339 with an explicit offset.

Pages are always sorted by recorded time, then event ID, newest first. --time-field changes filtering, not sorting. Defaults can be changed with events_limit, events_timezone, and events_time_field settings.

synkro events --type verdict --limit 5 --details
synkro events --type '*.created' --exclude billing --from 2026-09-22 --to 2026-09-22 --tz UTC
synkro events --list-types --json

See Events for examples of reading prompts, exact tool inputs, semantic checks, matched Rules and tool results.

Sign-in and account

synkro login

Starts your sign-in to Synkro. You complete it in the browser. It reuses an existing sign-in unless forced. To connect an agent to your account, use synkro onboard and approve its connection instead.

For device sign-in, open the printed link or visit https://app.sandbox.synkro.sh/device and enter the short code.

synkro logout

Signs out this installation. For an agent connection, Synkro first asks its human to approve the exact request on a Synkro page, then revokes that connection before clearing saved credentials. Other agent connections and the human's browser session stay signed in. It has no options beyond --help.

synkro whoami

Shows the installation's identity and organization. --json returns machine-readable output. The current CLI attempts normal renewal before reporting an expired saved sign-in; it also reports credentialState, the resolved credentialFile path, a safe authError code and authErrorMessage when available, and guidance for incomplete setup. An unreadable credential file is distinct from an installation with no saved sign-in. These checks do not create an account or collect a pending agent connection; use synkro onboard resume for that.

On earlier versions, whoami only reports the cached token. An expired display does not establish that renewal is broken; synkro onboard claim --json checks and renews a connected agent using its saved setup.

Account commands

Account commands show the signed-in organization's billing account. All accept --json. Status and payment require an organization owner; members can read balance and usage.

synkro account usage accepts exactly one of --daily (the default), --weekly, or --monthly. It accepts --from MM-DD-YY and --to MM-DD-YY. Dates use UTC day boundaries and include the end date. With neither date, it shows the last 30 days up to now. This date format is different from synkro events.

synkro account pay --amount DOLLARS chooses a top-up amount. Without it, Synkro uses the account's minimum top-up. The account's minimum and maximum are checked before checkout. With --json, the command prints the checkout URL, amount in cents, and environment instead of opening a browser. Complete payment in the secure checkout; creating a link alone does not add funds.

See Billing and usage for payment steps and access requirements.

Commands used by the integration

synkro grade --harness NAME --event NAME

Forwards one provider hook to the daemon. Both --harness and --event are required. Accepted harness names are claude_code, codex, antigravity, and cursor. Accepted event names are PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, SessionEnd, and Stop; preToolUse, postToolUse, beforeSubmitPrompt, sessionStart, and sessionEnd are also accepted where applicable. The event and payload must match the selected provider's hook contract.

--payload JSON supplies the raw hook body; omit it or pass --payload - to read standard input unchanged. The service validates the provider event, records it, and returns its native decision.

synkro mcp

Runs Synkro's MCP server over standard input and output. Optional --harness NAME identifies the hosting agent using one of the names above. The installer configures this where supported.

You do not need to run either manually during normal setup. See Supported agents.

Settings

CLI flags override environment variables, which override project synkro.toml, user ~/.synkro/synkro.toml, and bundled defaults, in that order. Use schema_version = 2 for a [settings] table. These files configure non-secret settings. Manage sign-in with synkro login and installation with synkro install. For errors, use Troubleshooting.

install_refresh_timeout_ms sets the installation refresh deadline, in milliseconds (default 10000). Its environment override is SYNKRO_INSTALL_REFRESH_TIMEOUT_MS.