synapsectl is the command-line client for discovering and controlling Synapse devices. It is distributed with the Synapse Python client and uses that client to call the Synapse API, stream Taps, transfer files, and manage Synapse Apps and peripheral plugins.

Install

We recommend installing synapsectl in a Python virtual environment:

python3 -m venv .venv
source .venv/bin/activate
pip install science-synapse

synapsectl --version
synapsectl --help

App and peripheral builds also require Docker. Gateware builds require a Lattice Radiant license. Model conversion for DSP execution requires Docker and the Qualcomm AI Runtime SDK.

Command Syntax

synapsectl [--uri DEVICE] [--verbose] COMMAND [ARGS]

Global option	Purpose
`-u DEVICE`, `--uri DEVICE`	Select a device by IP address or discovered device name. Place this option before the command, for example `synapsectl -u 192.168.42.1 info`.
`-v`, `--verbose`	Enable verbose client output.
`--version`	Print the installed `synapsectl` and Synapse API versions.
`-h`, `--help`	Show help. Add it after a command or subcommand for contextual help.

Commands that only build or inspect local files do not require --uri. Commands that communicate with a device require it unless explicitly noted.

Command Overview

Command	Function	Related concepts and APIs
`discover`	Find Synapse devices on the local network.	Info
`info`	Display device identity, state, storage, peripherals, and configuration.	Device Lifecycle, Info
`configure`, `start`, `stop`	Install and control a signal chain.	Configure, Start, Stop
`query`	Run unary or streaming device queries.	Query, StreamQuery
`logs`	Read retained logs or follow new log entries.	GetLogs, TailLogs
`taps`, `read`	Inspect or stream Taps, optionally recording broadband data to HDF5.	`Query(kListTaps)` and Tap data transport
`plot`	Plot a local Synapse recording.	Local operation; no device API call
`file`	List, download, or remove files through SFTP.	Filesystem
`apps`	Build, deploy, and list Synapse Apps.	Synapse App SDK, DeployApp, ListApps
`peripherals`	Build and deploy peripheral drivers and gateware.	Axon Peripheral SDK, DeployApp
`settings`	Read or update the device-defined settings schema.	Settings, Query, UpdateDeviceSettings
`deploy-model`	Convert and upload a machine learning model for use by Synapse Apps.	Filesystem, Synapse App SDK

Discover Devices

synapsectl discover

discover continuously displays the names and addresses of Synapse devices found on the local network. Stop discovery with Ctrl+C. A discovered name can be used anywhere a device identifier is accepted:

synapsectl -u my-device info

Inspect a Device

synapsectl -u $DEVICE info

info calls Info and summarizes the device identity, current lifecycle state, power and Storage Devices, discovered peripherals, and configured nodes and connections.

Use the Python Client Directly

synapsectl is built on the same Python client installed by science-synapse. Use the library directly when you need custom control flow, concurrent Tap streams, or application-specific processing:

from synapse.client.taps import Tap

tap = Tap("192.168.42.1", verbose=True)
available_taps = tap.list_taps()

tap_name = "broadband_source_1"
if tap_name not in [item.name for item in available_taps]:
    raise RuntimeError(f"Tap {tap_name} not found")

tap.connect(tap_name)
for message in tap.stream():
    print(message)