CLI Reference

Complete command reference for the three Singularity CLI tools — services, tasks, and scripts — plus app.py startup arguments.

Singularity ships three CLI entry points defined in pyproject.toml under [project.scripts]:

[project.scripts]
services = "cli.services:main"
tasks = "cli.tasks:main"
scripts = "cli.scripts:main"

After installing with uv sync, these commands are available directly in your shell.

services CLI

Service Management Utility. Discover, create, delete, enable, inspect, validate, and visualize services.

services list

List all discovered services.

Flag	Short	Type	Default	Description
`--detailed`	`-d`	flag	`false`	Show detailed information (path, endpoint, type, RPC status, methods)
`--json`	`-j`	flag	`false`	Output as JSON
`--all`	`-a`	flag	`false`	Include disabled and core services

services list
services list --detailed --all
services list --json

services info

Show detailed information about a specific service.

Argument	Type	Required	Description
`SERVICE_NAME`	`str`	Yes	Service name or path (e.g. `payments` or `v1/payments`)

services info payments
services info v1/auth

Output includes: path, module, API endpoint, class name, status (Active/DISABLED), docstring, HTTP methods, exposed routes, RPC attributes, blacklist, webhook events.

services create

Create a new service with boilerplate code.

Argument	Type	Required	Description
`SERVICE_NAME`	`str`	Yes	Service name or nested path (e.g. `users` or `v1/users`)

Flag	Short	Type	Default	Description
`--description`	`-d`	`str`	`""`	Description of the service (used in docstring)
`--template`	`-t`	choice	`crud`	Base template: `crud`, `minimal`, `empty`, or `webhook`
`--methods`	`-m`	`str`	(none)	Comma-separated HTTP methods (overrides template default). Valid: `get`, `post`, `put`, `delete`, `patch`.
`--rpc`		flag	`false`	Enable RPC exposure (`rpc_exposed = True`)
`--websocket` / `--ws`		flag	`false`	Add WebSocket support (`ws=connect` endpoint)
`--auth`		flag	`false`	Add JWT authentication (replaces GET with authenticated version)
`--db`		flag	`false`	Add database session dependency imports
`--overwrite`	`-i`	flag	`false`	Overwrite existing service if it exists

singularity generate service users
singularity generate service users -d "User management service"
singularity generate service v1/auth --template minimal --auth
singularity generate service billing --rpc --methods get,post
singularity generate service chat --websocket
singularity generate service stripe_hooks --template webhook
singularity generate service v1/github_hooks --template webhook --db

services delete

Delete or disable a service. Requires either --soft or --hard.

Argument	Type	Required	Description
`SERVICE_NAME`	`str`	Yes	Service name or path

Flag	Short	Type	Default	Description
`--soft`		flag	`false`	Disable service without deleting files (adds to `.services_disabled`)
`--hard`		flag	`false`	Permanently delete the service directory
`--force`	`-f`	flag	`false`	Skip confirmation prompt (with `--hard` only)

services delete old_service --soft
services delete old_service --hard
services delete old_service --hard --force

--soft and --hard are mutually exclusive. You must specify exactly one.

services enable

Re-enable a previously soft-deleted (disabled) service.

Argument	Type	Required	Description
`SERVICE_NAME`	`str`	Yes	Service name or path

services enable old_service

After enabling, restart the server to load the service.

services validate

Validate a service name and preview what would be created.

Argument	Type	Required	Description
`SERVICE_NAME`	`str`	Yes	Service name or path to validate

Flag	Short	Type	Default	Description
`--template`	`-t`	choice	`crud`	Base template: `crud`, `minimal`, `empty`, or `webhook`
`--rpc`		flag	`false`	Preview with RPC exposure
`--websocket` / `--ws`		flag	`false`	Preview with WebSocket support
`--auth`		flag	`false`	Preview with JWT authentication

services validate my_new_service
services validate v1/auth --template minimal --auth
services validate stripe_hooks --template webhook

Output includes: name, class name, directory, service file path, API endpoint, template, methods, RPC, acquire, websocket, auth, and the exact command to run.

services graph

Show the service dependency graph. Detects RPC descriptors, remote Microservice descriptors, and blacklist declarations.

Flag	Short	Type	Default	Description
`--json`	`-j`	flag	`false`	Output as JSON
`--dot`		flag	`false`	Output as DOT (Graphviz) format
`--all`	`-a`	flag	`false`	Include disabled and core services

services graph
services graph --json
services graph --dot
services graph --dot | dot -Tpng -o deps.png

Default output (ASCII): Shows Local RPC edges, Remote (cross-deployment) edges, Blacklisted entries, and Isolated services.

tasks CLI

Task Management Utility. Manage, list, run, and serve background tasks.

tasks list

List all available background tasks.

(no flags)

tasks list

Output: Table with columns: Name, Description, Params (count).

tasks info

Show detailed info and parameters for a task.

Argument	Type	Required	Description
`TASK_NAME`	`str`	Yes	The unique task identifier

tasks info send_email

Output includes: task name, description, parameter table (name, type, required, default), and config (notifications, max retries, retry delay, time limit).

tasks create

Create a new task file with boilerplate.

Argument	Type	Required	Description
`TASK_NAME`	`str`	Yes	Task name in snake_case (e.g. `send_email`)

Flag	Short	Type	Default	Description
`--description`	`-d`	`str`	`""`	Description of the task
`--overwrite`	`-i`	flag	`false`	Overwrite existing task file

singularity generate task send_email
singularity generate task send_email -d "Send transactional emails"

tasks run

Trigger a task manually.

Argument	Type	Required	Description
`TASK_NAME`	`str`	Yes	The unique task identifier
`ARGS`	`str...`	No	Positional arguments for the task

Flag	Short	Type	Default	Description
`--kwargs`	`-k`	`str`	(none)	JSON dictionary of keyword arguments
`--countdown`	`-c`	`int`	(none)	Delay in seconds before the task starts

tasks run send_email --kwargs '{"to": "user@example.com", "subject": "Hello"}'
tasks run process_order -k '{"order_id": "123"}' --countdown 30

tasks result

Check the status and result of a task.

Argument	Type	Required	Description
`TASK_ID`	`str`	Yes	The Celery task ID (returned by `tasks run`)

tasks result abc123-def456-789

Output: Task ID, State (PENDING, STARTED, SUCCESS, FAILURE, REVOKED), and Result/Error.

tasks worker

Start a Celery worker instance.

Flag	Type	Default	Description
`--concurrency`	`int`	`2`	Number of concurrent worker processes
`--loglevel`	choice	`info`	Logging level: `debug`, `info`, `warning`, `error`, `critical`
`--queues`	`str`	`"celery"`	Comma-separated list of queues to consume from
`--hostname`	`str`	(auto)	Set custom hostname for the worker
`--max-tasks-per-child`	`int`	`1000`	Max tasks per child process before recycling
`--prefetch-multiplier`	`int`	`1`	Prefetch multiplier
`--pool`	choice	`threads`	Pool implementation: `prefork`, `eventlet`, `gevent`, `threads`, `solo`
`--autoscale`	`str`	(none)	Enable autoscaling (format: `max,min`)
`--beat`	flag	`false`	Enable Celery Beat scheduler

tasks worker
tasks worker --concurrency 8 --pool gevent
tasks worker --queues celery,emails --loglevel debug
tasks worker --autoscale 10,3 --beat

When --pool gevent is used, gevent monkey patching is applied before any other imports. On Windows, --beat starts Celery Beat as a separate subprocess.

scripts CLI

Script Management Utility. Manages database migrations, data patches, and maintenance scripts.

scripts list

List all available executable scripts.

Flag	Type	Default	Description
`--detailed` / `--simple`	flag	`--detailed`	Show detailed or simple information

scripts list
scripts list --simple

scripts create

Create a new script with boilerplate code.

Argument	Type	Required	Description
`SCRIPT_NAME`	`str`	Yes	Script name in snake_case

Flag	Short	Type	Default	Description
`--description`	`-d`	`str`	`""`	Description of what the script does
`--overwrite`	`-i`	flag	`false`	Overwrite existing script if it exists

singularity generate script seed_data -d "Seed initial data"
singularity generate script add_user_roles -d "Add default user roles"

scripts run

Run an existing script by name or ID.

Argument	Type	Required	Default	Description
`IDENTIFIER`	`str`	No	(none)	Script name (e.g. `my_task`) or numeric ID. If omitted, lists all scripts.
`COMMAND`	choice	No	`run`	Action to perform: `run`, `rollback`, or `status`

scripts run seed_data
scripts run seed_data rollback
scripts run seed_data status
scripts run 1 status

scripts history

Show execution history of scripts from the database.

(no flags)

scripts history

scripts sync-hashes

Update script content hashes in the database. Used when script files have been edited and you want to mark them for re-execution.

(no flags)

scripts sync-hashes

scripts startup

Run all auto-run scripts (used during application startup).

(no flags)

scripts startup

app.py CLI Arguments

The application entry point app.py accepts the following command-line arguments via argparse:

uv run python app.py [OPTIONS]

Argument	Type	Default	Description
`--dev`	flag	`false`	Run in development mode with Uvicorn (auto-reload enabled). Excludes `scripts/`, `servers/`, `tests/`, `junk/*` from reload watching.
`--host`	`str`	`"0.0.0.0"`	Host to bind the server to
`--port`	`int`	`8000`	Port to bind the server to
`--workers`	`int`	`4`	Number of Gunicorn workers (production mode only)
`--timeout`	`int`	`600`	Worker timeout in seconds (production mode only)
`--no-heartbeat`	flag	`false`	Disable the RPC heartbeat loop (sets `SINGULARITY_NO_HEARTBEAT=1`)

Development Mode

uv run python app.py --dev
uv run python app.py --dev --port 3000
uv run python app.py --dev --no-heartbeat

Uses Uvicorn with reload=True. Ideal for local development.

Production Mode

uv run python app.py --host 0.0.0.0 --port 8000 --workers 4
uv run python app.py --workers 8 --timeout 300

Uses Gunicorn with UvicornWorker, keep-alive=10, and graceful-timeout=60.

The --no-heartbeat flag is useful during development or testing when you do not have Redis running but still want the app to start without RPC heartbeat errors.

On this page