> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synheart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AI & agents

> Reference for the synheart commands in the AI & agents group.

Every command also accepts the [global flags](/cli/reference/index#global-flags).

## `synheart guard`

Hold your coding agents to rules you set

Checks what a coding agent is about to do (push, merge, delete, deploy,
edit a protected file) against rules you wrote, before it runs. A rule either
asks you or stops the agent. Exceptions are scoped to a repository, branch or
path, expire after the time you set, and can only be granted by you at a
terminal.

Everything stays on this machine: your rules in \~/.synheart/guard/rules.yaml, a
repository's own rules in .synheart/guard.yaml, and a local log of which rules
fired (never the commands themselves). Start with 'synheart guard init', then
'synheart guard install' to hook it into Claude Code.

**Usage**

```bash theme={null}
synheart guard
```

**Subcommands**

* `synheart guard allow`: Allow a blocked action for a limited time
* `synheart guard check`: Test a shell command against your guard rules
* `synheart guard init`: Create your guard rules file
* `synheart guard install`: Hook the guard into Claude Code
* `synheart guard report`: Summarise what the guard stopped, asked and allowed
* `synheart guard rules`: List the guard rules in force here
* `synheart guard sync`: Refresh team rules and upload day totals now
* `synheart guard team`: Use your organization's guard rules

**Examples**

```bash theme={null}
# Create your rules file, then hook the guard into Claude Code
synheart guard init
synheart guard install --write
# Test a command against your rules
synheart guard check git push --force origin main
# See what the guard did this week
synheart guard report
```

### `synheart guard allow`

Allow a blocked action for a limited time

Lets what a rule stops or asks about through, in the scope you give and
only until the time you set (default 1h, at most 168h). Use it when you know a
one-off action is fine. Only you can run it, at a terminal; an agent cannot.

Find rule IDs with 'synheart guard rules'. Scope the exception with --repo,
\--branch or --path; without them it applies everywhere.

**Usage**

```bash theme={null}
synheart guard allow <rule-id> [flags]
```

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--branch` | `string` | - | Limit the exception to this branch |
| `--for` | `duration` | `1h0m0s` | How long the exception lasts, up to 168h (for example 30m or 2h) |
| `--note` | `string` | - | Reason for the exception, kept in your local record |
| `--path` | `string` | - | Limit the exception to paths matching this glob |
| `--repo` | `string` | - | Limit the exception to this repository (owner/name) |

**Examples**

```bash theme={null}
# Allow a force-push on one branch for two hours
synheart guard allow no-force-push --branch feat/rewrite --for 2h
# Allow pushes to protected branches in one repository for a hotfix
synheart guard allow no-push-protected --repo synheart-ai/synheart-cloud --for 30m --note "hotfix"
```

**JSON output:** not supported. This command does not print a JSON body.

### `synheart guard check`

Test a shell command against your guard rules

Shows what the guard would do with a shell command in the current
directory, without running it: stop, ask, or let it through, and which rule
decided. Everything after 'check' is the command to test, flags included, except
a trailing --json, which prints the actions, verdict and matching rules as an
object. Needs no login and no network.

**Usage**

```bash theme={null}
synheart guard check <command>
```

**Examples**

```bash theme={null}
# Would this force-push be stopped?
synheart guard check git push --force origin main
# Quote compound commands
synheart guard check 'cd ../web && gh pr create --base dev'
# The same answer for a script
synheart guard check git push --force origin main --json
```

**JSON output:** supported. Add `--json` (or `--format json`) to print a machine-readable body.

### `synheart guard init`

Create your guard rules file

Writes \~/.synheart/guard/rules.yaml, from a starter set or from a file you
give with --from, and checks that it loads. Refuses to overwrite an existing
file. Only you can run it, at a terminal. Next step: 'synheart guard install'.

**Usage**

```bash theme={null}
synheart guard init [flags]
```

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--from` | `string` | - | Start from this rules file instead of the starter set |

**Examples**

```bash theme={null}
# Start from the built-in rules
synheart guard init
# Start from your team's file
synheart guard init --from ./team-rules.yaml
```

**JSON output:** not supported. This command does not print a JSON body.

### `synheart guard install`

Hook the guard into Claude Code

Without flags, prints the Claude Code settings that run the guard before and
after each action. With --write, merges them into \~/.claude/settings.json, or
into .claude/settings.local.json in this directory with --project. It keeps
every other setting and hook, saves a backup first, and changes nothing when
run again.

**Usage**

```bash theme={null}
synheart guard install [flags]
```

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--project` | `bool` | `false` | With --write, use this directory's .claude/settings.local.json instead of \~/.claude/settings.json |
| `--write` | `bool` | `false` | Add the hook to Claude Code's settings instead of printing it |

**Examples**

```bash theme={null}
# Preview the settings
synheart guard install
# Add the hook for all your projects
synheart guard install --write
# Add it for this directory only
synheart guard install --write --project
```

**JSON output:** not supported. This command does not print a JSON body.

### `synheart guard report`

Summarise what the guard stopped, asked and allowed

Counts how often each rule fired over a period: stopped, asked, or let
through. It reads the local log, which never holds commands or file paths. With
\--json it prints the counts as an object. Needs no login and no network.

**Usage**

```bash theme={null}
synheart guard report [flags]
```

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--since` | `duration` | `168h0m0s` | How far back to report, as a duration (for example 24h) |

**Examples**

```bash theme={null}
# The last seven days
synheart guard report
# The last day
synheart guard report --since 24h
```

**JSON output:** supported. Add `--json` (or `--format json`) to print a machine-readable body.

### `synheart guard rules`

List the guard rules in force here

Lists the rules that apply in the current directory, merged from your
rules file, the repository's .synheart/guard.yaml and your team's rules, each
with its verdict (stop or ask; "shadow" means it only logs). Active exceptions
follow. With --json it prints an object with the rules under "items" and the
active exceptions under "exceptions". Needs no login and no network.

**Usage**

```bash theme={null}
synheart guard rules
```

**Examples**

```bash theme={null}
# List the rules and exceptions that apply here
synheart guard rules
# As JSON
synheart guard rules --json
```

**JSON output:** supported. Add `--json` (or `--format json`) to print a machine-readable body.

### `synheart guard sync`

Refresh team rules and upload day totals now

Fetches your organization's current rules from Synapse and uploads the day
totals of which rules fired, never commands, paths or prompts. The guard does
this in the background about every 15 minutes; run it to do it now. Needs: you
joined a team ('synheart guard team join') and network access.

**Usage**

```bash theme={null}
synheart guard sync [flags]
```

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--quiet` | `bool` | `false` | Print nothing (used by the hook) |

**Examples**

```bash theme={null}
# Sync now
synheart guard sync
```

**JSON output:** not supported. This command does not print a JSON body.

### `synheart guard team`

Use your organization's guard rules

Applies your organization's rules from Synapse on this machine, ahead of
your own, and shares day totals of which rules fired with your team. Never a
command, a file path or a prompt. Use 'join' to start, 'status' to check, and
'leave' to stop.

**Usage**

```bash theme={null}
synheart guard team
```

**Subcommands**

* `synheart guard team join`: Enforce your organization's agent rules here
* `synheart guard team leave`: Stop using your organization's rules here
* `synheart guard team status`: Show your guard team and last sync

**Examples**

```bash theme={null}
# Start using your organization's rules
synheart guard team join
# Check the team and last sync
synheart guard team status
```

### `synheart guard team join`

Enforce your organization's agent rules here

Fetches your organization's rules from Synapse and enforces them ahead of
your own, then runs a first sync. Day totals of which rule fired (stopped,
asked, let through) are shared with your team, never a command, a file path or a
prompt. Only you can run it, at a terminal.

Needs: you are logged in ('synheart login') and network access. The
organization comes from your sign-in unless you pass --org.

**Usage**

```bash theme={null}
synheart guard team join [flags]
```

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--org` | `string` | - | Organization ID (default: the org from your sign-in) |

**Examples**

```bash theme={null}
# Join the team for your organization
synheart guard team join
# Join a specific organization
synheart guard team join --org org_acme_xyz
```

**JSON output:** not supported. This command does not print a JSON body.

### `synheart guard team leave`

Stop using your organization's rules here

Removes your organization's rules and the team link from this machine. Your
own rules keep applying. Only you can run it, at a terminal. Needs no network.

**Usage**

```bash theme={null}
synheart guard team leave
```

**Examples**

```bash theme={null}
# Leave the team
synheart guard team leave
```

**JSON output:** not supported. This command does not print a JSON body.

### `synheart guard team status`

Show your guard team and last sync

Shows the organization this machine takes rules from, the policy version,
when it last synced, and the last sync error if there was one. Says "not in a
team" when you have not joined. With --json it prints the same as an object.
Reads local state only.

**Usage**

```bash theme={null}
synheart guard team status
```

**Examples**

```bash theme={null}
# Show the team and last sync
synheart guard team status
```

**JSON output:** supported. Add `--json` (or `--format json`) to print a machine-readable body.

## `synheart mcp`

Connect AI agents through the MCP server

Exposes the Synheart CLI to AI agents (Claude Code, Cursor, Claude Desktop)
through the Model Context Protocol, so they can call its read-only commands as
tools. 'synheart mcp' on its own prints this help.

Add 'synheart mcp serve' to your agent's MCP server list to use it. See
docs/cli-mcp.md for the setup of each client.

**Usage**

```bash theme={null}
synheart mcp
```

**Subcommands**

* `synheart mcp serve`: Run the MCP server on stdin and stdout

**Examples**

```bash theme={null}
# Start the server (your agent's MCP client runs this)
synheart mcp serve
# Check it responds, without an agent
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | synheart mcp serve
```

### `synheart mcp serve`

Run the MCP server on stdin and stdout

Reads JSON-RPC 2.0 messages from stdin, one per line, and writes responses
to stdout. The server is read-only: it offers explain, doctor, config show,
auth status, whoami and list-scenarios, and never signs in or changes anything
on the agent's behalf.

An MCP client starts this command; it prints nothing until the client sends a
request. Needs no network of its own.

**Usage**

```bash theme={null}
synheart mcp serve
```

**Examples**

```bash theme={null}
# Start the server (your agent's MCP client runs this)
synheart mcp serve
# List its tools from a shell
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | synheart mcp serve
```

**JSON output:** not supported. This command does not print a JSON body.

## `synheart syni`

Chat with Syni, Synheart's state-aware assistant

Syni is Synheart's state-aware conversational layer. Run 'synheart syni'
in a terminal to chat interactively; use the subcommands for one-shot messages,
personas and past sessions.

Cloud chat needs you to be logged in and a plan that includes it (see
'synheart usage'). Without a terminal, or with --json or --no-repl, running
'synheart syni' prints this help instead. Pass --org, --tenant or --project (or
the matching SYNHEART\_\*\_ID variables) to choose the scope.

**Usage**

```bash theme={null}
synheart syni
```

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--org` | `string` | - | Organization ID (env: SYNHEART\_ORG\_ID) |
| `--project` | `string` | - | Project ID (env: SYNHEART\_PROJECT\_ID) |
| `--tenant` | `string` | - | Tenant ID (env: SYNHEART\_TENANT\_ID) |

**Subcommands**

* `synheart syni chat`: Send a message to Syni
* `synheart syni personas`: List Syni personas
* `synheart syni sessions`: Inspect Syni chat sessions
* `synheart syni version`: Show installed syni-spec and syni-runtime versions

**Examples**

```bash theme={null}
# Chat interactively
synheart syni
# Ask one question and get the answer
synheart syni chat "How is my recovery?"
# See the available personas
synheart syni personas
```

### `synheart syni chat`

Send a message to Syni

Sends a message to Syni in the cloud and prints the reply. With a message
it runs once and exits; with none, in a terminal, it opens an interactive chat.
Pass a persona ID first to talk to a specific persona, and --session to continue
an earlier conversation. Use --no-repl to require a message.

Needs: you are logged in, a plan that includes cloud chat, and network access.
With --json it prints the reply as an object.

**Usage**

```bash theme={null}
synheart syni chat [persona] [message] [flags]
```

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--mode` | `string` | `cloud_only` | Execution mode: cloud\_only, local\_first or local\_only |
| `--model` | `string` | - | Model ID (from GET /v1/models) |
| `--no-repl` | `bool` | `false` | Require a message instead of opening the interactive REPL |
| `--persona` | `string` | - | Persona ID or legacy key |
| `--session` | `string` | - | Continue this session (ID from an earlier chat) |

**Examples**

```bash theme={null}
# Ask one question
synheart syni chat "Why is my HRV down?"
# Ask a specific persona
synheart syni chat focus.coach.v1 "Help me focus"
# Continue a session and get JSON
synheart syni chat --session sess_abc "Continue" --json
```

**JSON output:** supported. Add `--json` (or `--format json`) to print a machine-readable body.

### `synheart syni personas`

List Syni personas

Lists the personas you can chat with, each with its ID. Use an ID with
'synheart syni chat \<persona>'. Needs: you are logged in, network access and a
project ID (--project, SYNHEART\_PROJECT\_ID, or platform.project in
.synheart/config.yaml). With --json it prints the list.

**Usage**

```bash theme={null}
synheart syni personas
```

**Subcommands**

* `synheart syni personas show`: Show one Syni persona

**Examples**

```bash theme={null}
# List personas for a project
synheart syni personas --project prj_123
# As JSON
synheart syni personas --project prj_123 --json
```

**JSON output:** supported. Add `--json` (or `--format json`) to print a machine-readable body.

### `synheart syni personas show`

Show one Syni persona

Prints the details of the persona with the given ID. Needs you to be
logged in and network access. With --json it prints the persona as an object.

**Usage**

```bash theme={null}
synheart syni personas show <id>
```

**Examples**

```bash theme={null}
# Show a persona
synheart syni personas show focus.coach.v1
# As JSON
synheart syni personas show focus.coach.v1 --json
```

**JSON output:** supported. Add `--json` (or `--format json`) to print a machine-readable body.

### `synheart syni sessions`

Inspect Syni chat sessions

Work with your Syni chat sessions. Use 'synheart syni sessions show' to
read one, and pass its ID to 'synheart syni chat --session' to continue it.

**Usage**

```bash theme={null}
synheart syni sessions
```

**Subcommands**

* `synheart syni sessions show`: Show a Syni session and its messages

**Examples**

```bash theme={null}
# Read a session
synheart syni sessions show sess_abc123
```

### `synheart syni sessions show`

Show a Syni session and its messages

Prints a chat session and its messages. Needs you to be logged in and
network access. With --json it prints the session as an object.

**Usage**

```bash theme={null}
synheart syni sessions show <session_id>
```

**Examples**

```bash theme={null}
# Read a session
synheart syni sessions show sess_abc123
# As JSON
synheart syni sessions show sess_abc123 --json
```

**JSON output:** supported. Add `--json` (or `--format json`) to print a machine-readable body.

### `synheart syni version`

Show installed syni-spec and syni-runtime versions

Prints the versions of the syni-spec and syni-runtime packages installed in
the current project. It reads the vendored packages, or the pins in
synheart.lock when they are not vendored yet; "source" in the JSON says which.
Reads local files only, so it needs no login and no network.

**Usage**

```bash theme={null}
synheart syni version
```

**Examples**

```bash theme={null}
# Show the installed versions
synheart syni version
# As JSON
synheart syni version --json
```

**JSON output:** supported. Add `--json` (or `--format json`) to print a machine-readable body.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.