# CLI commands

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

Source: https://docs.synkro.sh/reference/cli

For signup with your agent, account claiming and first-Rule verification, use the [Quickstart](/quickstart) and its [CLI instructions](https://app.sandbox.synkro.sh/auth.md). The commands below cover installation, Rules, events and account management. Check which CLI version is installed:

```sh
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](/guides/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:

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

Use test cards only. Keep an existing production installation separate. See the [Quickstart](/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](https://app.sandbox.synkro.sh/auth.md). You can also [request access on the website](https://synkro.sh/request-access). 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.

| Option | What it does |
| --- | --- |
| `--project DIR` | Name the exact project root. Required with `--rule` when starting verification. |
| `--rule PACKAGE/RULE` | Select the package-qualified Rule ID. |
| `--proposal DIR` | Inspect a staged policy outside the active project. Cannot be combined with `--verdict` or `--published`. |
| `--published` | Verify the active policy while retaining the proposal's saved example receipts. |
| `--example-decision UUID` | Supply an existing semantic check decision in authored example order. Repeat for each example. |
| `--verdict UUID` | Select an existing verdict from an action run through your agent. |
| `--json` | Print structured progress and evidence. |

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](/integrations/github)
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](/guides/rules#find-suggestions-from-review-feedback)
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.

| Command | What it does |
| --- | --- |
| `synkro discover start OWNER/REPO` | Freeze a window from the last completed incremental scan. `--project DIR` defaults to the current project. |
| `synkro discover github connect` | Print the GitHub connection page URL and current connection status. |
| `synkro discover github status` | Check whether your connection has private-repository access. |
| `synkro discover github disconnect` | Disconnect your GitHub account in the current organization. Keeps saved findings and Rules. |
| `synkro discover start OWNER/REPO --from LOWER --to UPPER` | Freeze an explicit historical window. Both RFC3339 bounds are required: lower exclusive, upper inclusive. This never advances the incremental checkpoint. |
| `synkro discover show SCAN_ID` | Read saved progress, evidence, or the completed receipt. |
| `synkro discover collect-scan SCAN_ID` | Collect every review page within that saved scan's bounds. |
| `synkro discover collect OWNER/REPO --from LOWER --to UPPER` | Read review evidence without saving a scan or findings. Add `--connected` for private repositories. |
| `synkro discover schema submission` | Print the exact accepted-evidence JSON Schema. No sign-in or network request. |
| `synkro discover submit SCAN_ID --file FILE` | Submit the complete accepted-evidence JSON file. Return admitted sources, deduplicated sources, active Rules and findings to reassess. |
| `synkro discover schema completion` | Print the exact investigated-suggestion JSON Schema. |
| `synkro discover complete SCAN_ID --file FILE` | Save investigated suggestions and reassessments. Only a completed incremental scan moves its checkpoint. |
| `synkro discover findings OWNER/REPO` | List open suggestions for this installation and project. Accepts `--project DIR`, `--limit N`, `--after UUID` and `--include-dismissed`. |
| `synkro discover finding FINDING_ID` | Read one suggestion, its evidence and any dismissal details. |
| `synkro discover dismiss FINDING_ID --reason "Already covered"` | Dismiss a suggestion. Keeps its evidence and leaves Rules unchanged. |
| `synkro discover propose FINDING_ID` | Read the finding and the current rule-management instructions so your agent can prepare a Rule for your approval. Does not create or activate a Rule. |

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](/guides/rules#find-suggestions-from-review-feedback)
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.

| Option | What it does |
| --- | --- |
| `--no-browser` | Use device sign-in instead of a local browser callback. Keep the CLI running until sign-in finishes. |
| `--force` | Sign in again before reinstalling. |
| `--daemon-url URL` | Save the Synkro service address for this installation. |

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**.

| Option | What it does |
| --- | --- |
| `--check` | Check for a newer CLI release without installing or updating components. |
| `--yes` | Apply available component updates without prompting. |

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:

```sh
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.

| Option | What it does |
| --- | --- |
| `--path DIR` | Initialize the project containing this directory. |
| `--without-package` | Skip the local Rule package. This also permits initialization outside a Git worktree. |

### `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.

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

See [Rules](/guides/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:

```sh
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.

```toml
[[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.

| Option | What it does |
| --- | --- |
| `--path DIR` | Check the project containing this directory. |
| `--rule ID` | Check only this unqualified Rule ID, such as `block-demo-marker`, not `package/block-demo-marker`. Repeat for several IDs. |
| `--deterministic-only` | Test only deterministic examples. Skip semantic examples. |
| `--json` | Print the report as JSON. |

## 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`

| Option | What it does |
| --- | --- |
| `--json` | Print one structured trace document. |
| `--verbose` | Expand chronological evidence and invocation journals in text output. |
| `--daemon-url URL` | Override the service for this invocation without changing saved settings. |

`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.

| Field | Contents |
| --- | --- |
| `schemaVersion`, `traceId` | Format version (`1`) and full W3C trace ID. |
| `summary` | `outcome` (`success`, `failure`, `unknown`), nullable `errorCode`, `verdict`, `startedAt`, `cliTotalUs`, `outputAvailableOffsetUs`, `postResponseDiagnosticsUs`, `verdictAvailableOffsetUs`, `partitionTotalUs`, `serverError`; `empty` boolean. Success describes transport completion, not an allow verdict. |
| `phases[]` | `id`, display `label`, nullable `offsetUs`/`durationUs`, and `basis` (`cli_monotonic`, `cli_span_clock`, `daemon_monotonic`, `cross_host_estimate`). `cli_span_clock` identifies offsets reconstructed from same-process span timestamps. |
| `steps[]` | `step`, `startedAt`, `roundTripUs`, nullable `bodyUs` and `outsideBodyUs`. Missing body evidence, including replay, remains null. |
| `buckets[]` | Stable `id`, nullable `durationUs` and `percentOfCliTotal`, ordered by duration descending, unknowns last. |
| `journal` | `availability`, `truncated`, parent-first `invocations[]` (original `invocation`, `depth`, `parentMissing`, nullable `offsetUs`/`durationUs`, ordered `entries[]`), and `unattachedEntries[]` when an invocation is missing. |
| `log[]` | Deduplicated chronological evidence: `at`, `source`, `label`, nullable `durationUs`. |
| `notes[]` | Human-readable measurement limitations. |
| `raw` | Unmodified `server` inspection (null on request failure) and `pendingObservations[]`. These upstream records retain their own API shape. |

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.

| Option | What it does |
| --- | --- |
| `--type SELECTOR` | Include matching types. Accepts exact types, categories, `category.*`, `*.suffix`, or `*`. Repeat or separate values with commas. |
| `--exclude SELECTOR` | Remove matches after inclusion. Repeat or separate values with commas. |
| `--list-types` | List the daemon's actual event types and sources. Cannot be combined with filters, `--cursor`, `--limit`, or `--details`. |
| `--from TIME` | Inclusive start. Omit for no lower time bound. |
| `--to TIME` | Exclusive end, except a date-only value includes that entire calendar day. Omit for no upper time bound. |
| `--time-field recorded\|occurred` | Choose which event clock the time filters use. Default is `recorded`. |
| `--tz ZONE` | Parse and display times in `local`, `UTC`, or an IANA time zone such as `America/Chicago`. Default is local. |
| `--id UUID` | Find one event by its exact ID. |
| `--correlation UUID` | Find events in one correlation. |
| `--causation UUID` | Find events caused by this ID. |
| `--source NAME` | Include a source name. Repeat or separate names with commas. |
| `--user-id ID` | Filter by exact authenticated user ID within the events you can already access. Omit to include all accessible users. |
| `--limit N` | Set page size. Default is 50; the daemon enforces its configured maximum. |
| `--cursor VALUE` | Continue from a returned page cursor. Do not combine it with new filters. |
| `--details` | Print each complete event envelope and typed payload. |
| `--json` | Return a JSON page, or JSON taxonomy with `--list-types`. Diagnostics remain on stderr. |
| `--daemon-url URL` | Use a different daemon for this invocation only. It does not change the saved install setting. |

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.

```sh
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](/guides/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.

| Option | What it does |
| --- | --- |
| `--no-browser` | Use device sign-in. Keep the CLI running until it finishes. |
| `--force`, `-f` | Sign in again even if credentials are already saved. |
| `--port PORT` | Set the local browser **callback** port. This is not the daemon port. |

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.

| Command | What it shows or does |
| --- | --- |
| `synkro account` | Account status. Same as `synkro account status`. |
| `synkro account status` | Billing email, payment method, balance, and environment. |
| `synkro account balance` | Current balance, amount funded, and amount spent. |
| `synkro account usage` | Decision counts, charges, and token usage over a period. |
| `synkro account pay` | Creates a payment link to add funds and tries to open it in a browser. |

`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](/guides/billing) 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](/reference/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](/troubleshooting).

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