CLI

The Scheduler0 CLI is a command-line interface for interacting with the Scheduler0 API. Built with Go for native installation on Windows, macOS, and Linux.

Installation

macOS and Linux — install script (recommended)

The quickest way to install on macOS or Linux. Auto-detects your OS and CPU architecture, verifies the checksum, and places the binary in /usr/local/bin:

curl -fsSL https://raw.githubusercontent.com/scheduler0/scheduler0-cli/main/install.sh | bash

Pin a specific version:

curl -fsSL https://raw.githubusercontent.com/scheduler0/scheduler0-cli/main/install.sh | VERSION=0.0.4 bash

Override the install directory:

curl -fsSL https://raw.githubusercontent.com/scheduler0/scheduler0-cli/main/install.sh | INSTALL_DIR=$HOME/.local/bin bash

Manual binary install

Pre-built archives are published for every release on the Releases page.

Archive naming convention: scheduler0_<version>_<os>_<arch>.tar.gz

macOS

# Apple Silicon (M1/M2/M3)
curl -fsSL -o scheduler0.tar.gz \
  https://github.com/scheduler0/scheduler0-cli/releases/latest/download/scheduler0_0.0.4_darwin_arm64.tar.gz

# Intel
curl -fsSL -o scheduler0.tar.gz \
  https://github.com/scheduler0/scheduler0-cli/releases/latest/download/scheduler0_0.0.4_darwin_amd64.tar.gz

tar -xzf scheduler0.tar.gz
sudo mv scheduler0 /usr/local/bin/
scheduler0 --version

macOS Gatekeeper: if the binary is blocked on first run, clear the quarantine flag:
xattr -d com.apple.quarantine /usr/local/bin/scheduler0

Linux

# amd64 (most servers and desktops)
curl -fsSL -o scheduler0.tar.gz \
  https://github.com/scheduler0/scheduler0-cli/releases/latest/download/scheduler0_0.0.4_linux_amd64.tar.gz

# arm64 (Raspberry Pi, Graviton, etc.)
curl -fsSL -o scheduler0.tar.gz \
  https://github.com/scheduler0/scheduler0-cli/releases/latest/download/scheduler0_0.0.4_linux_arm64.tar.gz

tar -xzf scheduler0.tar.gz
sudo mv scheduler0 /usr/local/bin/
scheduler0 --version

Windows

Download the .zip archive from the Releases page:

scheduler0_0.0.4_windows_amd64.zip

Extract scheduler0.exe and move it to a directory that is on your PATH (e.g. C:\Program Files\scheduler0\), or add the extraction directory to your PATH via System Properties → Environment Variables.

Verify the checksum

Every release includes a checksums.txt (SHA-256). To verify manually:

# Download checksums
curl -fsSL -O https://github.com/scheduler0/scheduler0-cli/releases/latest/download/checksums.txt

# macOS
shasum -a 256 -c <(grep "scheduler0_0.0.4_darwin_arm64.tar.gz" checksums.txt)

# Linux
sha256sum -c <(grep "scheduler0_0.0.4_linux_amd64.tar.gz" checksums.txt)

Docker

Pre-built multi-arch images (linux/amd64, linux/arm64) are published to Amazon ECR Public on every release.

Find the full image URI on the ECR Public Gallery page — the URI has the form:

public.ecr.aws/<alias>/scheduler0-cli:<version>

# Pull latest
docker pull public.ecr.aws/<alias>/scheduler0-cli:latest

# Pull a specific version
docker pull public.ecr.aws/<alias>/scheduler0-cli:0.0.4

Finding the alias: open the ECR Public Gallery page and copy the URI shown there, or run:
aws ecr-public describe-registries --region us-east-1 \
  --query 'registries[0].aliases[0].name' --output text

Run a one-off command:

docker run --rm \
  -v "$HOME/.scheduler0:/root/.scheduler0" \
  public.ecr.aws/<alias>/scheduler0-cli:latest \
  --help

Mount ~/.scheduler0 so the container can read your local credentials written by scheduler0 init. You can also pass credentials directly via flags:

docker run --rm \
  public.ecr.aws/<alias>/scheduler0-cli:latest \
  --base-url https://api.scheduler0.com \
  --api-key YOUR_KEY \
  --api-secret YOUR_SECRET \
  --account-id YOUR_ACCOUNT_ID \
  projects list

Using the image in CI

# GitHub Actions example
- name: Get ECR image URI
  id: ecr
  run: |
    alias=$(aws ecr-public describe-registries \
      --region us-east-1 \
      --query 'registries[0].aliases[0].name' \
      --output text)
    echo "image=public.ecr.aws/${alias}/scheduler0-cli:0.0.4" >> "$GITHUB_OUTPUT"

- name: List projects
  run: |
    docker run --rm \
      ${{ steps.ecr.outputs.image }} \
      --base-url ${{ vars.SCHEDULER0_BASE_URL }} \
      --api-key ${{ secrets.SCHEDULER0_API_KEY }} \
      --api-secret ${{ secrets.SCHEDULER0_API_SECRET }} \
      --account-id ${{ secrets.SCHEDULER0_ACCOUNT_ID }} \
      projects list

From Source

git clone https://github.com/scheduler0/scheduler0-cli.git
cd scheduler0-cli
go build -o scheduler0 .
sudo mv scheduler0 /usr/local/bin/

Quick Start

Initialize credentials:

scheduler0 init

The CLI supports two authentication methods:

API Key Authentication (Managed/Hosted)

For managed or hosted Scheduler0 instances, you'll be prompted for:

Base URL (e.g., https://api.scheduler0.com)
API Key
API Secret
Account ID

Or provide via flags:

scheduler0 init \
  --base-url https://api.scheduler0.com \
  --api-key your-api-key \
  --api-secret your-api-secret \
  --account-id your-account-id

Basic Authentication (Self-Hosted)

For self-hosted Scheduler0 instances, you'll be prompted for:

Base URL (e.g., http://localhost:7070)
Username (set during infrastructure setup)
Password (set during infrastructure setup)

Or provide via flags:

scheduler0 init \
  --base-url http://localhost:7070 \
  --username your-username \
  --password your-password \
  --auth-type basic

Credentials are saved to ~/.scheduler0/config.json and will be used for all subsequent commands.

Check cluster health:

scheduler0 healthcheck

List projects:

scheduler0 projects list

Commands

Projects

# List projects
scheduler0 projects list [--limit 10] [--offset 0] [--order-by date_created] [--order-direction desc]

# Get project details
scheduler0 projects get <project-id>

# Create a project
scheduler0 projects create --name "My Project" --description "Description" --created-by "user-id"

# Update a project
scheduler0 projects update <project-id> --description "New description" --modified-by "user-id"

# Delete a project
scheduler0 projects delete <project-id> --deleted-by "user-id"

Jobs

# List jobs
scheduler0 jobs list [--project-id <id>] [--limit 10] [--offset 0]

# Get job details
scheduler0 jobs get <job-id>

# Create a job
scheduler0 jobs create \
  --project-id 123 \
  --timezone "UTC" \
  --spec "0 30 * * * *" \
  --data '{"key": "value"}' \
  --created-by "user-id"

# Update a job
scheduler0 jobs update <job-id> \
  --spec "0 0 * * * *" \
  --status "inactive" \
  --modified-by "user-id"

# Delete a job
scheduler0 jobs delete <job-id> --deleted-by "user-id"

AI-Powered Job Creation

Create job configurations from natural language prompts using AI:

# Create job configurations from a natural language prompt
scheduler0 prompt \
  --prompt "Send weekly reports every Monday at 9 AM" \
  --purposes "reporting,communication" \
  --events "weekly_cycle" \
  --recipients "team@example.com,manager@example.com" \
  --channels "email" \
  --timezone "America/New_York"

# Simple prompt (only required field)
scheduler0 prompt --prompt "Follow up 2 days after the demo"

Note: This endpoint requires credits. Each prompt execution consumes 1 credit. If you have insufficient credits, you'll receive an error.

Prompt Requirements:

--prompt: Required, must be between 1 and 160 characters (after trimming whitespace)
--purposes: Optional, max 5 items, each item max 36 characters
--events: Optional, max 5 items, each item max 36 characters
--recipients: Optional, max 5 items, each item max 36 characters
--channels: Optional, max 5 items, each item max 36 characters
--timezone: Optional, timezone for scheduling calculations

Executors

# List executors
scheduler0 executors list [--limit 10] [--offset 0]

# Get executor details
scheduler0 executors get <executor-id>

# Create a webhook executor
scheduler0 executors create \
  --name "webhook-executor" \
  --type "webhook_url" \
  --webhook-url "https://example.com/webhook" \
  --webhook-method "POST" \
  --webhook-secret "secret" \
  --created-by "user-id"

# Update an executor
scheduler0 executors update <executor-id> \
  --name "updated-name" \
  --modified-by "user-id"

# Delete an executor
scheduler0 executors delete <executor-id> --deleted-by "user-id"

Local Executor

The local executor lets you run scheduled jobs as shell commands on a machine you control — no public endpoint required. The CLI pulls jobs from the server, executes them locally, and batches execution logs back when connectivity is available.

Setup walkthrough

Step 1 — Register the executor

Create a local executor record on the server. This stores the command (and optional workingDir) that the CLI will invoke for every job trigger.

scheduler0 local-executor register \
  --name "My Local Executor" \
  --command "/usr/local/bin/process-job.sh" \
  --working-dir "/home/deploy/myapp"

The executor's ID and name are saved automatically to ~/.scheduler0/config.json — you only need to register once per machine.

Step 2 — Create a dedicated credential

The local executor service authenticates using a Scheduler0 credential. Create one with read, write, and execute scopes via the dashboard or CLI:

scheduler0 credentials create --created-by "user123" --scopes "read,write,execute"

Save the returned apiKey and plaintextSecret — you will need them in the next step. The plaintextSecret is returned only once at creation time and is used as the X-Secret-Key header value in all API requests.

Step 3 — Start the service

scheduler0 local-executor start \
  --api-key "YOUR_API_KEY" \
  --api-secret "YOUR_API_SECRET"

The service runs in the foreground. It:

Pulls jobs assigned to this executor every 1 minute
Executes each job by running the registered command (with job data on stdin and in env vars)
Writes results to a local SQLite cache (~/.scheduler0/local-executor.db)
Batch-reports execution logs back to the server every 5 minutes, or immediately when 50 or more uncommitted logs accumulate

Stop it with Ctrl+C for a graceful shutdown.

Command reference

# Register a local executor on the server and save it to local config
scheduler0 local-executor register \
  --name <name> \
  --command <shell-command> \
  [--working-dir <dir>]

# Start the local executor service (reads executor from local config)
scheduler0 local-executor start \
  --api-key <key> \
  --api-secret <secret>

Offline resilience

When the server is unreachable, the CLI continues to schedule and execute jobs from its local cache. All execution results are persisted in the local SQLite database and flushed to the server once connectivity is restored.

Environment variables passed to the command

Variable	Value
`SCHEDULER0_JOB_ID`	Job ID
`SCHEDULER0_EXECUTION_ID`	Unique execution identifier
`SCHEDULER0_JOB_DATA`	Raw contents of the job's `data` field
`SCHEDULER0_JOB_SPEC`	Cron spec

Job data is also written to the command's stdin as a JSON object.

Executions

# List executions
scheduler0 executions \
  --start-date "2024-01-01T00:00:00Z" \
  --end-date "2024-12-31T23:59:59Z" \
  [--project-id <id>] \
  [--job-id <id>] \
  [--limit 10] \
  [--offset 0]

Credentials

# List credentials
scheduler0 credentials list [--limit 10] [--offset 0]

# Get credential details
scheduler0 credentials get <credential-id>

# Create a credential (returns apiKey and plaintextSecret; save the secret immediately)
scheduler0 credentials create --created-by "user-id"

# Update a credential
scheduler0 credentials update <credential-id> --archived true --modified-by "user-id"

# Archive a credential
scheduler0 credentials archive <credential-id> --archived-by "user-id"

# Delete a credential
scheduler0 credentials delete <credential-id> --deleted-by "user-id"

# Re-encrypt all active credentials after rotating the server's SecretKey (self-hosting only)
# Requires basic auth (--username / --password or auth_type=basic in config)
scheduler0 credentials rotate-secret

note

credentials rotate-secret is a self-hosting only command. You must update SecretKey in your secrets source before running it. The command calls POST /api/v1/credentials/rotate-secret with Basic Auth and the X-Peer: cmd header. See Credential docs — Rotating the Server's Secret Key for the full operator sequence.

Healthcheck

# Check cluster health (no authentication required)
scheduler0 healthcheck

Backup and Restore (Self-Hosted)

# Start automatic timestamped backup
scheduler0 backup start

# Restore from backup (file name, or S3 object key when S3 is configured)
scheduler0 backup restore db-20260113-143000.db

See Backup and Restore for full details.

Authentication

Scheduler0 CLI supports two authentication methods:

1. API Key Authentication (Managed/Hosted)

For managed or hosted Scheduler0 instances, use API Key + Secret authentication:

X-API-Key: Your API key
X-Secret-Key: Your API secret
X-Account-ID: Your account ID

2. Basic Authentication (Self-Hosted)

For self-hosted Scheduler0 instances, use username and password set during infrastructure setup:

Username and password configured during Scheduler0 setup
Uses HTTP Basic Authentication
No account ID required (single-tenant)

The CLI will automatically detect which authentication method to use based on your configuration.

Configuration

Credentials are stored in ~/.scheduler0/config.json:

API Key Authentication:

{
  "base_url": "https://api.scheduler0.com",
  "api_key": "your-api-key",
  "api_secret": "your-plaintext-secret",
  "account_id": "your-account-id",
  "auth_type": "api_key"
}

Note: api_secret here is the plaintextSecret returned once when you created the credential.

Basic Authentication (Self-Hosted):

{
  "base_url": "http://localhost:7070",
  "username": "your-username",
  "password": "your-password",
  "auth_type": "basic"
}

With a registered local executor:

{
  "base_url": "https://api.scheduler0.com",
  "api_key": "your-api-key",
  "api_secret": "your-plaintext-secret",
  "account_id": "your-account-id",
  "auth_type": "api_key",
  "local_executor": {
    "id": 42,
    "name": "My Local Executor",
    "command": "/usr/local/bin/process-job.sh",
    "working_dir": "/home/deploy/myapp"
  }
}

The local_executor block is written automatically by scheduler0 local-executor register. You do not need to edit it manually.

You can override the saved configuration using flags on any command.

Examples

Complete Workflow (Webhook Executor)

# 1. Initialize with API key authentication
scheduler0 init

# 2. Create a project
scheduler0 projects create --name "My Project" --created-by "user-123"

# 3. Create an executor
scheduler0 executors create \
  --name "webhook" \
  --type "webhook_url" \
  --webhook-url "https://api.example.com/webhook" \
  --webhook-method "POST" \
  --created-by "user-123"

# 4. Create a job (or use AI prompt)
scheduler0 jobs create \
  --project-id 1 \
  --timezone "UTC" \
  --spec "0 30 * * * *" \
  --data '{"message": "Hello"}' \
  --created-by "user-123"

# Alternative: Use AI to generate job configurations
scheduler0 prompt \
  --prompt "Send weekly reports every Monday at 9 AM" \
  --purposes "reporting" \
  --timezone "America/New_York"

# 5. List executions
scheduler0 executions \
  --start-date "2024-01-01T00:00:00Z" \
  --end-date "2024-12-31T23:59:59Z"

Local Executor Workflow

# 1. Initialize CLI
scheduler0 init

# 2. Register the local executor (saved to ~/.scheduler0/config.json)
scheduler0 local-executor register \
  --name "data-processor" \
  --command "/home/deploy/scripts/process.sh"

# 3. Assign jobs to the local executor from the dashboard or via API
#    (set executor_id to the ID returned by the register command above)

# 4. Create a dedicated credential with execute scope
scheduler0 credentials create --created-by "user-123" --scopes "read,write,execute"

# 5. Start the local executor service
scheduler0 local-executor start \
  --api-key "YOUR_API_KEY" \
  --api-secret "YOUR_API_SECRET"
# The service runs continuously: pull → execute → report, repeat

Self-Hosted Features

Note for Self-Hosted Users: Account Management, Feature Management, and Async Tasks Management APIs are designed for users who run Scheduler0 in their own infrastructure and need granular control over team access and resource usage.

Accounts

# Create an account
scheduler0 accounts create --name "My Account"

# Get account details
scheduler0 accounts get <account-id>

Async Tasks

# Get async task status (e.g., after creating a job)
scheduler0 async-tasks get <request-id>

GitHub Repository

The CLI source code is available at: https://github.com/scheduler0/scheduler0-cli

Installation​

macOS and Linux — install script (recommended)​

Manual binary install​

macOS​

Linux​

Windows​

Verify the checksum​

Docker​

Using the image in CI​

From Source​

Quick Start​

API Key Authentication (Managed/Hosted)​

Basic Authentication (Self-Hosted)​

Commands​

Projects​

Jobs​

AI-Powered Job Creation​

Executors​

Local Executor​

Setup walkthrough​

Command reference​

Offline resilience​

Environment variables passed to the command​

Executions​

Credentials​

Healthcheck​

Backup and Restore (Self-Hosted)​

Authentication​

1. API Key Authentication (Managed/Hosted)​

2. Basic Authentication (Self-Hosted)​

Configuration​

Examples​

Complete Workflow (Webhook Executor)​

Local Executor Workflow​

Self-Hosted Features​

Accounts​

Async Tasks​

GitHub Repository​