Developer tools

Synal CLI

Use the Synal API directly from your terminal, scripts, or an LLM with shell access. The CLI is available for anyone to download and install. Setup and API use require an API key from an active yearly subscription.

Let your LLM set it up

Paste this into an assistant with terminal access, such as Claude Code or Codex. It will install the CLI and guide you through connecting your account. You'll need an API key from an active yearly subscription; provide it through a secret environment variable or the CLI's hidden prompt, rather than pasting it into the chat.

Setup prompt

Install and set up the Synal CLI in my environment so you can use its API for me.

1. Check my OS and whether Python 3.9+ is installed. If Python is missing, help me install it using the appropriate method for this environment.
2. Download the standalone CLI from https://app.synal.to/downloads/synal and inspect the source. It uses only the Python standard library. On macOS/Linux, install it as ~/.local/bin/synal, make it executable, and ensure ~/.local/bin is on PATH. On Windows, save it in a user-owned location and run it with py -3. Do not overwrite an unrelated existing synal command.
3. Run synal --help (or the equivalent Python invocation) to verify installation and learn the commands.
4. Configure authentication. API access requires an active yearly Synal subscription. I can get my API key at https://app.synal.to/api_key. If SYNAL_API_KEY is already supplied securely in your environment, run synal setup to validate and save it. Otherwise, guide me to supply SYNAL_API_KEY through this environment's secret settings, or have me run synal setup in my own terminal and enter the key at its hidden prompt. Resume once the key is available. Never ask me to paste the key into chat, print it, put it in command arguments, or commit it to a repository.
5. Run synal events --per-page 1 to verify authenticated access. If the API returns 401, help me replace the key; if it returns 403, explain that an active yearly subscription is required. Only report setup complete after this check succeeds.
6. Tell me where the CLI and config were saved and show a few example commands. Responses are JSON. Discovery and unlocks are asynchronous; poll contacts or unlock-status after requesting them. Do not discover or unlock contacts as part of this setup.

1. Install

Requires Python 3.9 or later. No additional packages are needed. On macOS or Linux:

mkdir -p "$HOME/.local/bin"
curl --fail --show-error --silent https://app.synal.to/downloads/synal -o "$HOME/.local/bin/synal"
chmod +x "$HOME/.local/bin/synal"
export PATH="$HOME/.local/bin:$PATH"
synal --help

Add the PATH export to your shell profile to keep it across sessions. Run these commands again to update. You can also download the CLI source, inspect it, and run python3 synal --help. On Windows, download the file and use py -3 synal --help.

2. Set up your API key

Sign in, subscribe to the yearly plan, then copy your key from the API key page. Monthly subscriptions do not include API access.

synal setup

Paste your key at the hidden prompt. Setup verifies API access before saving the key to ~/.config/synal/config.json (or under XDG_CONFIG_HOME) with owner-only permissions on macOS and Linux. Keep this file private. Run setup again after regenerating your key.

3. Use the API

Replace the example event and contact IDs with IDs from your responses.

# Browse the feed and inspect an event
synal events --page 1 --per-page 25
synal event 123
synal contacts 123

# Request discovery with the token returned by contacts
synal discover 123 --token TOKEN_FROM_CONTACTS
synal contacts 123

# Request contact access, then poll for the result
synal unlock 456
synal unlock 456 --channel phone
synal unlock-status 456

Discovery and unlocks run asynchronously. A successful command means the request was accepted; poll contacts for discovery state or unlock-status for the requested channel's email_unlocked or phone_unlocked flag and status. Email is the default; phone lookup must be explicitly requested. See the API reference for response fields and terminal states.

Scripts and LLMs

Supply SYNAL_API_KEY through your runner's secret environment to use the CLI without an interactive prompt or a saved config file. It takes precedence over a saved key. Keep the key out of prompts, source control, and command arguments. Anyone can install the tool; each API caller needs a key with active yearly access.

# With SYNAL_API_KEY injected by your runner:
synal events --per-page 10
synal unlock --help

Responses are JSON on stdout, including pagination and asynchronous job state. Operational errors are JSON on stderr. Exit codes: 0 for an accepted API request, 1 for authentication, network, or API errors, and 2 for invalid command arguments. Use --help on any command to discover its arguments.

Troubleshooting

401: The key is missing, invalid, or has been regenerated. Run setup again or update SYNAL_API_KEY.
403: Your account needs an active yearly subscription, including after a subscription expires.
422: Refresh the discovery token from the contacts response and check the requested unlock channel.