Skip to main content


Sinapsis
Sinapsis CLI

Run Agents, inspect Templates, and manage local or Cloud workloads from your terminal.

Installation · Profiles · Jobs · Cloud features · Scheduling · Autocompletion

Installation

Python 3.13 or newer is required. The CLI is published as sinapsis-cli and installs the sinx, sinx-venv, sinx-api, and sinx-cloud commands.

Install it as a standalone CLI with uv:

uv tool install sinapsis-cli

Or install it in a Python environment:

uv pip install sinapsis-cli
# or
pip install sinapsis-cli

No additional package index is needed for a standard installation.

sinx --help

Execution profiles

Sinapsis CLI supports three execution backends. The commands you see depend on the selected profile.

Profile Entry point What it does
Local Python (local) sinx-venv Runs Agents directly with installed Python packages; inspects locally available Templates.
Local API (local-api) sinx-api Submits and manages jobs using a local Sinapsis API.
Cloud (cloud) sinx-cloud Runs Cloud jobs and manages saved Agents, Templates, files, integrations, and account resources.

sinx uses your configured default profile, initially local. You can override it for an individual invocation:

sinx jobs run agent.yaml                     # Current default profile
sinx local jobs run agent.yaml               # Direct Python execution
sinx local-api jobs run agent.yaml           # Local API
sinx cloud jobs run agent.yaml               # Cloud API

The dedicated executables are shortcuts for those three built-in profiles:

sinx-venv jobs run agent.yaml
sinx-api jobs run agent.yaml
sinx-cloud jobs run agent.yaml

Selecting or configuring cloud does not automatically change the default profile used by sinx.

Configure a profile

# Configure only Cloud, including account sign-in
sinx-cloud configure

# Configure only the local API
sinx-api configure

# Configure only direct local execution
sinx-venv configure

# Interactive setup of all profiles and the default profile
sinx configure

New to Sinapsis Cloud? Visit sinapsis.tech to create an account before running sinx-cloud configure.

To inspect your current configuration:

sinx profiles list
sinx-cloud profiles show cloud
sinx profiles show local
sinx profiles show local-api

The built-in Cloud API URL is https://api.sinapsis.tech and the local API URL defaults to http://localhost:8000. sinx-cloud profiles show cloud displays the saved Cloud profile settings; it is not an authentication test.

Choose a default or create another profile

sinx profiles default cloud
sinx profiles default local

# Create a second Cloud environment
sinx profiles create staging --backend cloud --api-url https://YOUR-API-HOST
sinx staging configure
sinx staging jobs list

# Choose an execution profile just for one terminal session
SINAPSIS_PROFILE=cloud sinx jobs list

Profiles can also be managed with sinx profiles delete NAME and inspected with sinx profiles show NAME. Run sinx profiles --help for the full profile command reference.

Running Agents

Agent definitions are YAML files that connect reusable Templates. An example:

agent:
  name: hello_world

templates:
  - template_name: Input
    class_name: InputTemplate
    attributes: {}

  - template_name: HelloWorld
    class_name: HelloWorld
    template_input: Input
    attributes:
      display_text: "Hello from Sinapsis!"

Install the Template packages required by your Agent in the environment where it runs. The example requires the corresponding InputTemplate and HelloWorld implementations.

Local Python execution

Run directly in the selected Python environment:

sinx-venv jobs run agent.yaml

Local Python jobs execute directly; the CLI does not offer API-style jobs status, jobs stream, or jobs cancel commands for this backend.

Local API and Cloud jobs

Both API-backed profiles support asynchronous job management:

# Submit a job
sinx-api jobs run agent.yaml
sinx-cloud jobs run agent.yaml

# Submit and follow the execution (either API-backed profile)
sinx-cloud jobs run agent.yaml --wait
sinx-cloud jobs run agent.yaml --stream

# Inspect a job
sinx-cloud jobs status JOB_ID
sinx-cloud jobs result JOB_ID
sinx-cloud jobs stream JOB_ID
sinx-cloud jobs cancel JOB_ID

The same jobs status, jobs result, jobs stream, and jobs cancel subcommands are available under sinx-api for local API jobs. An explicit JOB_ID can identify a job created elsewhere, subject to access permissions.

When a job ID is omitted, the CLI uses the most recent job remembered for the selected profile:

sinx-cloud jobs status
sinx-cloud jobs result

The following additional job options are available:

Option Availability Effect
--wait Local API, Cloud Wait for the job to finish and retrieve results.
--stream Local API, Cloud Stream execution output.
--result Local API, Cloud Request retained results after submission.
--save-dir DIR / -o DIR Run, result, and stream commands where offered Choose an output directory for saved artifacts (direct Python execution prints its result).
--print-only All run commands; API results/stream Print output rather than saving artifacts.
--refresh Cloud jobs result, and jobs run --result Retrieve a fresh result rather than a cached one.
--verbose / -v Cloud jobs status Include the full Agent definition.

--wait, --stream, and --result are mutually exclusive when used with jobs run. For Cloud jobs run, --refresh requires --result.

Job history

Every backend includes a local command history:

sinx-venv jobs list
sinx-api jobs list
sinx-cloud jobs list
sinx-cloud jobs list --all-profiles

# Clear the remembered jobs for one profile
sinx-cloud jobs clear

jobs list displays jobs recorded by this CLI; it is not a list of all jobs held by the Cloud service. Clearing local history does not cancel remote jobs.

Discover Templates

Templates installed locally

sinx-venv templates show-all
sinx-venv templates show-all --names-only
sinx-venv templates docstring TemplateName
sinx-venv templates example-config TemplateName
sinx-venv templates example-config TemplateName --output json

Template configuration examples support pretty, json, and yaml output formats.

Templates available in Cloud

sinx-cloud templates list
sinx-cloud templates search "object detection"
sinx-cloud templates search "speech" --limit 20
sinx-cloud templates show TEMPLATE_UUID
sinx-cloud templates packages

Cloud search also supports --package, --tag, --offset, and --limit filters. The Cloud catalogue reflects the Templates and packages accessible to your account; it may differ from what is installed locally.

Cloud features

Cloud adds commands for working with reusable Agents, assets, and integrations. Run sinx-cloud <group> --help to see all options.

Saved Agents and immutable versions

sinx-cloud agents register agent.yaml --version v1
sinx-cloud agents list
sinx-cloud agents versions AGENT_UUID
sinx-cloud agents version AGENT_UUID VERSION_UUID
sinx-cloud agents publish AGENT_UUID updated-agent.yaml --version v2

register saves an Agent without executing it. publish creates a new immutable version. By default, agents list shows explicitly registered Agents; use agents list --all to include Agents saved through execution and earlier records.

Scheduling an existing Agent version is covered in Scheduling.md, including automatic version selection and recurring runs.

Files

sinx-cloud files upload ./input.csv
sinx-cloud files list
sinx-cloud files search input.csv
sinx-cloud files get FILE_ID --output ./input.csv
sinx-cloud files fetch AGENT_ID FILE_ID --output ./artifact.bin

get retrieves a stored file by ID; fetch retrieves a file produced in an Agent's staging area.

Secrets

sinx-cloud secrets create my-service-key   # Prompts securely for the value
sinx-cloud secrets list
sinx-cloud secrets get SECRET_UUID
sinx-cloud secrets delete SECRET_UUID

Use the interactive prompt to avoid passing secret values in shell history. get displays secret metadata, not the secret value.

API keys

sinx-cloud api-keys permissions
sinx-cloud api-keys create --name my-integration --scope files:read --expire 7d
sinx-cloud api-keys list
sinx-cloud api-keys delete

The CLI supports scopes, expiry durations, and optional Agent restrictions. Save new API key values when they are created; they cannot be revealed later.

Webhooks

sinx-cloud webhooks register --help
sinx-cloud webhooks list
sinx-cloud webhooks show WEBHOOK_UUID
sinx-cloud webhooks public-url WEBHOOK_UUID
sinx-cloud webhooks toggle WEBHOOK_UUID --inactive
sinx-cloud webhooks delete WEBHOOK_UUID

Webhook registration accepts an integration name, a provider, and optional credential and payload-schema settings.

Package registry access

sinx-cloud packages indexes
sinx-cloud packages login
sinx-cloud packages logout

These commands help configure uv credentials for supported Sinapsis package indexes. Access to a registry may depend on your account and the registry's availability.

CLI telemetry controls

CLI telemetry is optional and can be inspected or controlled directly:

sinx config telemetry status
sinx config telemetry preview
sinx config telemetry info
sinx config telemetry enable
sinx config telemetry history --limit 10
sinx config telemetry disable
sinx config telemetry disable --clear

Telemetry is off unless enabled or explicitly overridden in the environment. preview lets you inspect an example of the information collected without storing or transmitting it. No personal information is ever collected.

Shell autocompletion

Install command, subcommand, and option completion for each executable you use:

sinx --install-completion
sinx-venv --install-completion
sinx-api --install-completion
sinx-cloud --install-completion

Restart your shell or reload its configuration after installation. Completion is installed separately for each executable.

Resources

License

sinapsis-cli is dual-licensed under MIT OR Apache-2.0.

Metadata

Release files for sinapsis_cli 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sinapsis_cli 1.0.0
File Size Uploaded Provenance Actions
sinapsis_cli-1.0.0.tar.gz 150.6 kB Without provenance Details for sinapsis_cli-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sinapsis_cli 1.0.0
File Interpreter ABI Platform Actions
sinapsis_cli-1.0.0-py3-none-any.whl Python 3 none any Details for sinapsis_cli-1.0.0-py3-none-any.whl

Total release size: 229.2 kB

Release files / sinapsis_cli-1.0.0.tar.gz

Download URL sinapsis_cli-1.0.0.tar.gz
Size 150.6 kB
Tags Source
SHA-256 checksum
How to use checksums
15ad2b8390a71df1de343e1714c3f454c3c1a664de25e7d3aac117cba4c2c1df
BLAKE2b-256 checksum
How to use checksums
6576a4d04738a57040136c2083c66ea1dbace17d4166c8b265e47d9ccc9d0884
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.6.17

Release files / sinapsis_cli-1.0.0-py3-none-any.whl

Download URL sinapsis_cli-1.0.0-py3-none-any.whl
Size 78.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4eaf24277f5cbccfcf3db20a98aafe99a87fb6a1a72a6f7d474b3141a10246d4
BLAKE2b-256 checksum
How to use checksums
433e344a9480e3f8bf61410830d30df4bf7da201144f2205823a2304c9c91790
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.6.17

Security for sinapsis_cli 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page