CLI Tools

# Default compact listing
services list

# Detailed table with path, endpoint, type, and RPC status
services list --detailed

# Include disabled and core services
services list --all

# JSON output for programmatic consumption
services list --json

# Combine flags
services list --detailed --all

Found 5 active service(s):
  Name             | Endpoint               | RPC
  --------------------------------------------------
  users            | /api/v1/users          | Yes
  payments         | /api/v1/payments       | Yes
  stripe [wh]      | /api/v1/stripe         | No
  notifications    | /api/v1/notifications  | No
  analytics        | /api/v1/analytics      | No

services info payments

  Service: payments
  Path: services/v1/payments
  Module: services.v1.payments.service
  API Endpoint: /api/v1/payments
  Class: PaymentsService
  Status: Active

  Methods:
    - get      /api/v1/payments
    - post     /api/v1/payments

  HTTP Exposed:
    - POST     /api/v1/payments/refund  (post_refund)
    - GET      /api/v1/payments/status  (get_status)

  Attributes:
    rpc_exposed: True
    blacklist: ['public']

# Basic CRUD service
singularity generate service users

# Nested path with description
singularity generate service v1/users -d "User management service"

# Minimal template with auth
singularity generate service v1/auth --template minimal --auth

# Webhook service with database access
singularity generate service v1/stripe --template webhook --db

# Service with RPC and custom methods
singularity generate service billing --rpc --methods get,post

# Service with WebSocket support
singularity generate service chat --websocket

# Overwrite existing service
singularity generate service users --overwrite

# Soft delete -- disable without removing files
services delete old_service --soft

# Hard delete -- permanently remove files
services delete old_service --hard

# Skip confirmation prompt
services delete old_service --hard --force

services enable old_service

services validate v1/analytics

# Preview with specific options
services validate v1/analytics --template crud --rpc --auth

  Name: v1/analytics
  Class: AnalyticsService
  Directory: services/v1/analytics
  Service file: services/v1/analytics/service.py
  API Endpoint: /api/v1/analytics

  Configuration:
    Template: crud
    Methods: GET, POST, PUT, DELETE
    RPC: Yes
    Acquire: Yes
    WebSocket: No
    Auth: Yes

  Ready to create. Run:
    singularity generate service v1/analytics --template crud --rpc --auth

# ASCII output in the terminal
services graph

# Include disabled and core services
services graph --all

# JSON output
services graph --json

# DOT format for Graphviz
services graph --dot

# Pipe to Graphviz to render as PNG
services graph --dot | dot -Tpng -o deps.png

Service Dependencies:

  Local RPC:
    orders ──> payments
    orders ──> users

  Remote (cross-deployment):
    invoices ──> billing (https://billing.internal:8000)

  Blacklisted:
    payments x── public

  Isolated (no dependencies, not depended on):
    analytics
    notifications

# Start a playground session
services play users

# Nested service path
services play v1/billing

  Singularity Playground -- users (UsersService)
  Available methods: get, post, put, delete
  RPC dependencies: billing (auto-mocked)

  Commands: .help  .rpc  .ms  .calls  .quit

  > users> get()
    {"status": "ok", "users": []}

  > users> post(data={"name": "John"})
    {"status": "created", "data": {"name": "John"}}

  > users> .rpc billing get_balance {"balance": 100}
    OK: billing.get_balance -> {"balance": 100}

  > users> .calls
    RPC billing.get_balance({})

  > users> .quit

# Generate to the default path
services stubs

# Generate to a custom path
services stubs --output ./my_stubs.py

"""
Auto-generated RPC stubs -- do not edit.
Run `services stubs` to regenerate.
"""
from typing import Any

class PaymentsRPC:
  """Stub for 'payments' service."""
  async def get(self) -> Any: ...
  async def post(self, data: dict) -> Any: ...
  async def get_status(self, payment_id: str) -> Any: ...

class UsersRPC:
  """Stub for 'users' service."""
  async def get(self) -> Any: ...
  async def post(self, data: dict) -> Any: ...

# Install the dashboard extra
uv sync --extra dashboard

# Launch the dashboard
services dashboard

┌─────────────────────────────────────────────────────────┐
│  Singularity Dashboard              [q] quit  [?] help  │
├────────────────────────┬────────────────────────────────┤
│  Services        (5)   │  Service Detail                │
│  ─────────────────     │  ─────────────────────────     │
│  ● users     [RPC]     │  Name: users                   │
│  ● payments  [RPC]     │  Endpoint: /api/v1/users       │
│  ● orders              │  Methods: GET POST PUT DELETE   │
│  ○ analytics [disabled]│  RPC: Yes                      │
│  ◆ stripe    [webhook] │  Hooks: before(all), after(all)│
├────────────────────────┴────────────────────────────────┤
│  Dependency Graph                                       │
│  users ──▸ payments     orders ──▸ payments             │
├─────────────────────────────────────────────────────────┤
│  Logs                                                   │
│  12:03:01 INFO  Discovered 5 service(s)                 │
│  12:03:01 INFO  Dependency graph rendered               │
└─────────────────────────────────────────────────────────┘

tasks list

Found 3 tasks:
----------------------------------------------------------------------
Name                      | Description                    | Params
----------------------------------------------------------------------
send_email                | Send a transactional email     | 3
process_order             | Process an e-commerce order    | 3
generate_report           | Generate a PDF report          | 2

Use 'tasks info <task_name>' for parameter details.

tasks info send_email

Task: send_email
    Send a transactional email

    Parameters:
    --------------------------------------------------
    Name            Type       Required   Default
    --------------------------------------------------
    to              str        Y          -
    subject         str        Y          -
    body            str        Y          -

    Config:
      Notifications: log, callback
      Max Retries: 3 | Retry Delay: 60s | Time Limit: 3600s

# Create a task with a description
singularity generate task send_notification -d "Send push notifications to users"

# Overwrite an existing task
singularity generate task send_notification -d "Updated notification logic" --overwrite

# Run with keyword arguments (JSON)
tasks run send_email -k '{"to": "test@example.com", "subject": "Hello", "body": "World"}'

# Run with a countdown delay (task starts in 60 seconds)
tasks run process_order -k '{"order_id": "ord_123", "items": []}' -c 60

# Positional arguments
tasks run send_email test@example.com "Hello" "World"

tasks result abc12345-task-id

Task ID: abc12345-task-id
State: SUCCESS
Result: {'status': 'sent', 'to': 'test@example.com'}

# Default worker (2 threads)
tasks worker

# High-concurrency worker with gevent pool
tasks worker --concurrency 8 --pool gevent

# Worker with Beat scheduler for periodic tasks
tasks worker --beat

# Debug-level logging
tasks worker --loglevel debug

# Autoscaling between 2 and 10 workers
tasks worker --autoscale 10,2

# Consume from specific queues
tasks worker --queues celery,priority

# Detailed listing (default)
scripts list

# Simplified listing
scripts list --simple

Available Scripts (4 found)
=================================================================================
ID   Script Name                    Auto-run   Rerun    Deprecated   Affected Tables
----------------------------------------------------------------------------------
1    cleanup_orphaned_records       ON         OFF      No           temp_uploads
2    create_stripe_products         ON         OFF      No           products, prices
3    old_migration_v1               OFF        OFF      Yes          (none)
4    seed_initial_data              ON         ON       No           users, roles

# Create with a description
singularity generate script add_user_roles -d "Add default user roles to the database"

# Overwrite an existing script
singularity generate script add_user_roles -d "Updated roles" --overwrite

# Run a script (default action)
scripts run add_user_roles

# Force rerun even if already succeeded
scripts run add_user_roles run --force

# Check execution status
scripts run add_user_roles status

# Roll back a previously executed script
scripts run add_user_roles rollback

# Run by numeric ID
scripts run 2

# Check status by ID
scripts run 2 status

scripts history

Executed Scripts History (3 total)
============================================================
Script Name                         Status       Executed At          Modified   Hash
------------------------------------------------------------
create_stripe_products              SUCCESS      2024-06-15 10:23:01  Current    a1b2c3d4e5f6...
cleanup_orphaned_records            SUCCESS      2024-06-15 10:23:02  CHANGED    f6e5d4c3b2a1...
old_migration_v1                    ROLLED_BACK  2024-06-14 08:15:30  Missing    (none)

scripts sync-hashes

scripts startup