plexus-synapse: Schema-driven CLI for Plexus RPC servers

[ library, mit, network, program ] [ Propose Tags ] [ Report a vulnerability ]

Synapse is the command-line frontend for Plexus RPC. It discovers a server's methods at runtime and builds its commands, help text, parameter validation and output rendering from the schema, with no code generation or static configuration.


[Skip to Readme]

Flags

Manual Flags

NameDescriptionDefault
build-examples

Build example programs (schema-discovery)

Disabled
build-keychain-tests

Build and run SELF-8 keychain tests. These shell out to security on macOS and touch the real keychain; they're opt-in so default `cabal test` runs stay quiet. Enable with: cabal test -f build-keychain-tests

Disabled
live-tests

Build the suites that need a live service: cli-test, websocket-raw-test and ir-test (a substrate and registry on 127.0.0.1:4444; cli-test also a synapse binary at a fixed dist-newstyle path). Opt-in, so a default `cabal test` needs nothing running. Enable with: cabal test -f live-tests

Disabled

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.3.0.0, 3.5.0, 3.10.1, 3.13.0, 3.15.0, 3.17.3, 4.0.0, 4.1.0, 4.2.0
Change log CHANGELOG.md
Dependencies aeson (>=2.0 && <2.3), aeson-pretty (>=0.8 && <0.9), array (>=0.5 && <0.6), async (>=2.2 && <2.3), base (>=4.17 && <5), base64-bytestring (>=1.2 && <1.3), bytestring (>=0.11 && <0.13), case-insensitive (>=1.2 && <1.3), containers (>=0.6 && <0.8), crypton (>=1.0 && <1.2), directory (>=1.3 && <1.4), fast-logger (>=3.0 && <3.3), filepath (>=1.4 && <1.6), hashable (>=1.4 && <1.6), katip (>=0.8 && <0.9), mtl (>=2.3 && <2.4), mustache (>=2.4 && <2.5), network (>=3.1 && <3.3), optparse-applicative (>=0.18 && <0.19), plexus-protocol (>=0.8 && <0.9), plexus-synapse, prettyprinter (>=1.7 && <1.8), process (>=1.6 && <1.7), ram (>=0.20 && <0.23), regex-tdfa (>=1.3 && <1.4), scientific (>=0.3 && <0.4), stm (>=2.5 && <2.6), streaming (>=0.2 && <0.3), text (>=2.0 && <2.2), time (>=1.12 && <1.14), transformers (>=0.6 && <0.7), unix (>=2.7 && <2.9), unordered-containers (>=0.2 && <0.3), vector (>=0.12 && <0.14), websockets (>=0.13 && <0.14), yaml (>=0.11 && <0.12) [details]
Tested with ghc ==9.8.4, ghc ==9.12.4
License MIT
Copyright (c) 2025-2026 hypermemetic
Author hypermemetic
Maintainer hypermemetic@proton.me
Uploaded by hypermemetic at 2026-11-17T10:18:16Z
Category Network
Distributions
Reverse Dependencies 1 direct, 0 indirect [details]
Executables protocol-test-demo, validation-report-test, reporter-demo, schema-discovery, synapse
Downloads 93 total (30 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2026-11-17 [all 1 reports]

Readme for plexus-synapse-4.2.0

[back to package description]

synapse

The command line of every Plexus RPC service: it reads a service's own schema and offers its activations, methods and flags.

Most people want plexus-rpc

plexus-rpc is the front door to Plexus RPC: its README builds a service in a few lines of Rust and calls it. The service in every example below is that one: myservice, with an echo activation, on ws://127.0.0.1:4444.

Install

The package is plexus-synapse and its executable is synapse. It builds with GHC 9.8.4 and cabal. Version 4.2.0 builds from this repository, with plexus-protocol 0.8 checked out beside it:

git clone https://github.com/hypermemetic-ai/synapse
git clone https://github.com/hypermemetic-ai/plexus-protocol
cd synapse
echo 'packages: ../plexus-protocol/' > cabal.project.local
cabal update
cabal install exe:synapse -w ghc-9.8.4
synapse --version

Hackage holds plexus-synapse 4.1.0.

An example

Name the service, then an activation, and synapse lists its methods.

$ synapse myservice echo
echo v0.1.0
  Say things back.

USAGE
  synapse myservice echo <method> [flags]

METHODS
  count     Ticks from 1 up to `to`.
  schema    Get plugin or method schema

Run 'synapse myservice echo <method> --help' for its options.
Run 'synapse --help' for synapse's own options.

A method's flags are its parameters.

$ synapse myservice echo count --help
Ticks from 1 up to `to`.

Usage: synapse myservice echo count --to <TO>

Options:
  --to <uint32>  the last tick

A value may be read from a file (--flag @FILE) or stdin (--flag -);
@@text sends a literal @text.

Example:
  synapse myservice echo count --to 1

Run 'synapse --help' for synapse's own options.

A call prints each item of the answer as it arrives.

$ synapse myservice echo count --to 3
n: 1
type: tick
n: 2
type: tick
n: 3
type: tick

On a service with sign-in, a caller signs in once with a key, and every later call carries the session.

$ synapse _login myservice --key dev --as dev
signed in to myservice at 127.0.0.1:4444 as dev
  principal key:b379e10bed307ff7a5f367ef07433434729d4ab7589cace401cd957da8c73549
  scope     the key's own grants
  until     2026-11-12 03:22:56 UTC
  kept in   ~/.plexus/sessions/127.0.0.1_4444/dev.json
$ synapse myservice echo hello
you: key:b379e10bed307ff7a5f367ef07433434729d4ab7589cace401cd957da8c73549

Each block above is a file under plexus-rpc's examples/, which scripts/examples.sh there writes again from synapse's own output.

More

MIT.