The upnext CLI is installed with the upnext package. It provides commands for running services, interacting with tasks, and managing the server.
upnext run
Start workers and APIs defined in Python files.
upnext run <files...> [--only NAME] [--redis-url URL] [--verbose]
upnext.Worker and upnext.Api instances in the given files and starts them together.
Options:
| Option | Short | Description |
|---|
--only | -o | Only run specific components by name (repeatable) |
--redis-url | | Redis URL (overrides UPNEXT_REDIS_URL and constructor config) |
--verbose | -v | Enable verbose logging |
# Run a single service file
upnext run service.py
# Run multiple files
upnext run worker.py api.py
# Run only a specific component by name
upnext run service.py --only my-api
# Run multiple specific components
upnext run service.py -o my-api -o my-worker
# Override Redis URL
upnext run service.py --redis-url redis://localhost:6379
# With environment variables
UPNEXT_REDIS_URL=redis://localhost:6379 upnext run service.py
upnext call
Execute a registered task function directly from the command line.
upnext call <function-name> [--kwargs JSON]
# Call a task with keyword arguments
upnext call process_order --kwargs '{"order_id": "123", "items": ["A", "B"]}'
The worker must have been initialized (via upnext run or worker.initialize()) at least once so the function is registered in Redis.
upnext list
List all registered functions (tasks, cron jobs, event handlers).
Displays a table showing function names, types, and configuration.
upnext server start
Start the UpNext API server and web dashboard.
upnext server start [--host HOST] [--port PORT] [--backend BACKEND] [--database-url URL] [--redis-url URL] [--reload] [--verbose]
Backend-first: persistence backend is selected by --backend or UPNEXT_BACKEND. Passing --database-url does not select sqlite or postgres by itself.
| Option | Default | Description |
|---|
--host | 0.0.0.0 | Host to bind to |
--port | 8080 | Port to listen on |
--backend | UPNEXT_BACKEND or redis | Persistence backend: redis, sqlite, or postgres |
--database-url | UPNEXT_DATABASE_URL or unset | SQL database URL for server startup checks and migrations |
--redis-url | UPNEXT_REDIS_URL or unset | Redis URL for runtime streams and queue integration |
--reload | false | Enable auto-reload |
--verbose, -v | false | Enable verbose logging |
# Start with Redis persistence backend (default)
UPNEXT_BACKEND=redis \
UPNEXT_REDIS_URL=redis://localhost:6379 \
upnext server start --port 8080
# Start with SQLite persistence backend via CLI flag
UPNEXT_DATABASE_URL=sqlite+aiosqlite:///upnext.db \
UPNEXT_REDIS_URL=redis://localhost:6379 \
upnext server start --backend sqlite
# Start with PostgreSQL persistence backend (run migrations first)
UPNEXT_BACKEND=postgres \
UPNEXT_DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/upnext \
upnext server db upgrade head
UPNEXT_BACKEND=postgres \
UPNEXT_DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/upnext \
UPNEXT_REDIS_URL=redis://localhost:6379 \
upnext server start --port 8080
upnext server db
SQL migration commands powered by Alembic.
upnext server db upgrade
Run database migrations to the specified revision.
upnext server db upgrade <revision>
# Upgrade to latest
upnext server db upgrade head
# Upgrade to specific revision
upnext server db upgrade abc123
upnext server db current
Show the current migration revision.
upnext server db history
Show migration history.
