Introduction

SynapSeq accepts a local SPSQ file, a sequence URL, or standard input. Give it an optional output path to choose the rendered file; otherwise it creates a WAV named after the input in the current directory.

Usage

synapseq [options] <input> [output]

Input	Example
Local file	`session.spsq`
URL	`https://example.com/session.spsq`
Standard input	`-`

Output	Result
Omitted	Creates `<input>.wav`.
`output.wav`	Writes a WAV file.
`output.mp3`	Exports MP3 with ffmpeg.
`output.json` with `-dump`	Writes rendered sequence data.
`-`	Writes raw PCM, or JSON with `-dump`, to standard output.

Rendering

Use these commands to create audio, preview a sequence, validate it, or convert input.

Render audio

Pass a sequence without an output path to render a WAV next to your terminal session.

synapseq session.spsq
synapseq session.spsq calm-session.wav

`-play`

Play a sequence directly through ffplay. Run -doctor first if ffplay is not available.

synapseq -play session.spsq

`-mp3`

Export with ffmpeg. With no output path, SynapSeq creates an MP3 named after the input.

synapseq -mp3 session.spsq
synapseq session.spsq calm-session.mp3

`-test`

Load and validate an SPSQ sequence without generating audio.

synapseq -test session.spsq

`-dump`

Render the loaded sequence as JSON for inspection or tooling.

synapseq -dump session.spsq session.json
synapseq -dump session.spsq -

`-sbg`

Convert an SBaGen sequence into SPSQ. Review the result because the formats do not share every behavior.

synapseq -sbg session.sbg converted.spsq
synapseq -test converted.spsq

CLI tools

`-doctor`

Check whether ffmpeg is available for MP3 export and ffplay is available for playback.

synapseq -doctor

`-lsp`≥ 4.43.x

Start the SPSQ language server over standard input and output for an editor integration.

synapseq -lsp

`-quiet`

Suppress progress and other non-error output. Combine it with a render or Remote command in scripts.

synapseq -quiet session.spsq output.wav

`-no-color`

Disable ANSI color sequences in SynapSeq status output.

synapseq -no-color session.spsq

`-version`

Print the installed SynapSeq version, build date, operating system, and architecture.

synapseq -version

`-help`

Show the command-line help, including the public options available in the installed version.

synapseq -help

`-completion-bash`

Print a Bash completion script. Source it in the current shell or save it to your completion directory.

source <(synapseq -completion-bash)

`-completion-zsh`

Print a Zsh completion script for the current shell session.

source <(synapseq -completion-zsh)

AI

Generate an SPSQ sequence with an OpenAI-compatible chat-completions API. Set SYNAPSEQ_AI_API_KEY before running -ai.

`-ai`

Give SynapSeq a natural-language prompt and an optional output path. Use - to send SPSQ to standard output.

SYNAPSEQ_AI_API_KEY="your-api-key" synapseq -ai "Create a calm 20-minute progression" calm.spsq
synapseq -ai "10 minutes of relaxation" -

`-ai-model`

Choose the model sent to the configured provider. The default is gpt-4.1-mini.

synapseq -ai-model gpt-4.1-mini -ai "Create a focus session" focus.spsq

`-ai-base-url`

Point SynapSeq at an OpenAI-compatible API host, including a local or alternate provider.

synapseq -ai-base-url https://api.example.com/v1 -ai "Create a short rest" rest.spsq

`-ai-temperature`

Set the sampling temperature from 0 through 2. The default is 1.

synapseq -ai-temperature 0.4 -ai "Create a steady 15-minute session" steady.spsq

`-ai-timeout`

Set the maximum API request duration using a Go duration. The default is 5m.

synapseq -ai-timeout 90s -ai "Create a calm progression" calm.spsq

Environment configuration

Command options take precedence over environment variables, which take precedence over CLI defaults.

Variable	Purpose	Default
`SYNAPSEQ_AI_API_KEY`	Required API key.	—
`SYNAPSEQ_AI_MODEL`	Model name.	`gpt-4.1-mini`
`SYNAPSEQ_AI_BASE_URL`	OpenAI-compatible API host.	Provider default
`SYNAPSEQ_AI_TEMPERATURE`	Sampling temperature.	`1`
`SYNAPSEQ_AI_TIMEOUT`	Request timeout.	`5m`

SynapSeq Remote

Remote provides the curated sequence index through the CLI. Start with -sync to create or refresh the local index before listing, searching, or retrieving sequences.

`-sync`

Fetch the default Remote index and save it locally.

synapseq -sync

`-sync-url`

Fetch an index from a custom Remote base URL instead of the default source.

synapseq -sync-url https://example.com/synapseq-remote

`-list`

List the sequences available in the local Remote index.

synapseq -list

`-search`

Search sequence IDs, descriptions, and categories in the local index.

synapseq -search focus

`-info`

Show metadata and the description for a Remote sequence. The source is downloaded and validated before details are shown.

synapseq -info calm-progression

`-download`

Download a Remote sequence as <id>.spsq into the current directory or a directory you provide.

synapseq -download calm-progression
synapseq -download calm-progression ./sequences

`-get`

Download a Remote sequence and render it in one step. An optional output path controls the result.

synapseq -get calm-progression
synapseq -get calm-progression calm.mp3

`-clean`

Remove the local Remote cache. Run -sync again before the next Remote query.

synapseq -clean

Remote configuration

Set SYNAPSEQ_REMOTE_BASE_URL to use a custom Remote base URL without passing -sync-url. The value must be an origin with no path; SynapSeq requests /index.json from that origin.

SYNAPSEQ_REMOTE_BASE_URL=https://library.example.com synapseq -sync

Host a custom library

Serve an index.json document with the application/json content type at your configured origin. Each sequence and optional artwork value is a relative path resolved from the same origin.

{
  "version": "1.0.0",
  "lastUpdated": "2026-09-14T00:00:00Z",
  "entries": [
    {
      "id": "calm-focus",
      "name": "Calm Focus",
      "description": "A gentle sequence for a focused session.",
      "durationMinutes": 20,
      "sequence": "sequences/calm-focus.spsq",
      "artwork": "artwork/calm-focus.webp",
      "category": "Focus",
      "createdAt": "2026-09-14T00:00:00Z"
    }
  ]
}

With the example above, SynapSeq requests https://library.example.com/index.json and downloads the sequence from https://library.example.com/sequences/calm-focus.spsq.

Field	Requirement
`version`	Non-empty index version.
`lastUpdated` / `createdAt`	RFC 3339 timestamps.
`id`	Unique lowercase letters, numbers, and hyphens; it cannot begin or end with a hyphen.
`name` / `category`	Required non-empty text.
`durationMinutes`	Positive integer.
`sequence`	Safe relative path ending in `.spsq`.
`artwork`	Optional safe relative path.
`description`	Optional sequence description.

The index rejects unknown fields, external URLs, absolute paths, path traversal, and sequence paths that do not end in .spsq.

External tools

SynapSeq uses ffmpeg for MP3 export and ffplay for direct playback. Use explicit paths when they are not on your system PATH.

`-ffmpeg-path`

Set the executable that SynapSeq uses for MP3 export.

synapseq -ffmpeg-path /opt/homebrew/bin/ffmpeg -mp3 session.spsq

`-ffplay-path`

Set the executable that SynapSeq uses for direct playback.

synapseq -ffplay-path /usr/local/bin/ffplay -play session.spsq

Windows

These options are available only on Windows and change the current user’s file associations.

`-install-file-association`

Associate .spsq files with SynapSeq for double-click playback, and add the SBaGen conversion action to Explorer.

synapseq -install-file-association

`-uninstall-file-association`

Remove the SynapSeq .spsq association and the SBaGen Explorer conversion action.

synapseq -uninstall-file-association

View all documentation

Introduction

Rendering

Render audio

-play

-mp3

-test

-dump

-sbg

CLI tools

-doctor

-lsp≥ 4.43.x

-quiet

-no-color

-version

-help

-completion-bash

-completion-zsh

AI

-ai

-ai-model

-ai-base-url

-ai-temperature

-ai-timeout