### Worked Example: Dynamic Configuration

Source: https://docs.runwisp.com/configuration/substitution

A comprehensive example showing environment and file substitution for task scheduling, secrets, and notifier credentials.

```toml
[tasks.export]
cron = "${EXPORT_CRON}"               # schedule decided by the deploy env
run  = "/usr/local/bin/export"


[tasks.export.secrets]
API_TOKEN = "${file:secrets/export.token}"


[[notifier]]
id          = "slack-ops"
type        = "slack"
webhook_url = "${SLACK_OPS_WEBHOOK}"


[[notifier]]
id        = "tg-oncall"
type      = "telegram"
bot_token = "${file:~/.config/runwisp/tg.token}"
chat_id   = "-1001234567890"
```

--------------------------------

### cURL Example

Source: https://docs.runwisp.com/api/operations/gettasks

Shows how to make a GET request to the /api/tasks endpoint using cURL. This is useful for testing the API from the command line.

```curl
curl --request GET \
  --url http://localhost:9477/api/tasks
```

--------------------------------

### Globally install RunWisp with Bun

Source: https://docs.runwisp.com/getting-started/quick-start

Install RunWisp globally using Bun for persistent use.

```shell
bun add -g runwisp
```

--------------------------------

### Install, Status, Uninstall, and Print RunWisp Service Units

Source: https://docs.runwisp.com/operations/autostart

These commands manage the autostart configuration for the RunWisp daemon. Use `install` to set up systemd or launchd units, `status` to check their state, `uninstall` to remove them, and `install --print` to output the unit file for external management.

```bash
runwisp service install     # wire up systemd / launchd
runwisp service status      # show autostart wiring and any drift
runwisp service uninstall   # remove the unit (data dir is preserved)
runwisp service install --print > custom.service   # Ansible / Nix
```

--------------------------------

### Worked Example: Default and Overridden Settings

Source: https://docs.runwisp.com/configuration/defaults

This example demonstrates how to set default values and then override them for specific tasks and services. It illustrates the inheritance and precedence rules.

```toml
[defaults]
timeout             = "30m"     # most tasks should die after 30 minutes
log_max_size        = "50mb"    # smaller default, override for noisy tasks
keep_runs           = 100
keep_for            = "30d"
backoff_reset_after = "30s"     # services that stabilise in 30s reset


[tasks.heartbeat]
cron = "*/5 * * * *"
run  = "/usr/local/bin/heartbeat"
# inherits 30m timeout, 50mb log cap, 100 runs, 30d retention


[tasks.nightly-export]
cron          = "0 2 * * *"
timeout       = "4h"      # overrides default — exports take longer
log_max_size  = "500mb"   # overrides default — output is large
graceful_stop = "20s"     # this one needs more than the built-in 5s
run           = "/usr/local/bin/export"


[services.flaky-worker]
backoff_reset_after = "2m"     # overrides default — this one takes longer to stabilise
run                 = "/usr/local/bin/worker"

```

--------------------------------

### RunWisp starter configuration

Source: https://docs.runwisp.com/getting-started/quick-start

This is an example of the initial runwisp.toml file created by RunWisp. It includes a basic 'hello' task and commented-out examples for scheduling tasks with cron and running long-running services.

```toml
# Docs: https://docs.runwisp.com/configuration/overview/


[tasks.hello]
description = "Example task. Trigger it from the TUI (press r) or the Web UI."
run = "echo hello from runwisp"


# Schedule a task with cron:
# [tasks.heartbeat]
# cron = "* * * * *"
# run  = "date"


# Long-running service (auto-restart, supports replicas):
# [services.worker]
# instances = 1
# run       = "node ./worker.js"

```

--------------------------------

### Complete RunWisp Configuration Example

Source: https://docs.runwisp.com/configuration/overview

This example demonstrates a comprehensive runwisp.toml file, including storage safeguards, global defaults, task definitions with cron schedules and retry logic, and a service definition.

```toml
# Disk-usage safeguards
[storage]
max_size       = "5gb"
min_free_space = "500mb"


# Global defaults applied to every task unless overridden
[defaults]
timeout      = "1h"
log_max_size = "100mb"
log_on_full  = "drop_old"
keep_runs    = 50
keep_for     = "30d"


[tasks.backup-db]
group       = "Backups"
description = "Nightly database backup"
cron        = "0 2 * * *"
timeout     = "30m"
on_overlap  = "skip"
keep_runs   = 30
run = "pg_dump mydb | gzip > /backups/mydb-$(date +%F).sql.gz"


[tasks.process-event-queue]
description    = "Worker that retries with exponential backoff"
cron           = "*/10 * * * *"
on_overlap     = "queue"
retry_attempts = 3
retry_delay    = "2s"
retry_backoff  = "exponential"
run = "/usr/local/bin/process-queue"


[services.metrics-daemon]
description = "Always-on metrics collector"
run         = "/usr/local/bin/metrics-agent"

```

--------------------------------

### API Response Example (200 OK)

Source: https://docs.runwisp.com/api/operations/restartservice

This is an example of a successful response when restarting a service. It confirms the operation was acknowledged.

```json
{
  "$schema": "http://localhost:9477/schemas/StopRunOutputBody.json"
}
```

--------------------------------

### cURL Example

Source: https://docs.runwisp.com/api/operations/bulkrerunruns

Shows how to re-run tasks using cURL. This command-line example illustrates the POST request with a JSON payload for selecting and filtering runs.

```curl
curl --request POST \
  --url http://localhost:9477/api/runs/bulk/rerun \
  --header 'Content-Type: application/json' \
  --data '{ "except_ids": [ "example" ], "filter": { "search": "example", "status": "example", "task_name": "example" }, "ids": [ "example" ], "match_all": true }'
```

--------------------------------

### Globally install RunWisp with npm

Source: https://docs.runwisp.com/getting-started/quick-start

Install RunWisp globally using npm for persistent use.

```shell
npm install -g runwisp
```

--------------------------------

### Runwisp Service Install Flags

Source: https://docs.runwisp.com/operations/autostart

Flags for installing a runwisp service, controlling confirmation, output, and installation path.

```bash
runwisp service install
  -y, --yes       skip the install confirmation (does not skip --purge)
      --print     write the rendered unit to stdout and exit
      --dry-run   print the plan and exit without writing
      --force     overwrite a hand-edited unit
      --system    install /etc/systemd/system/ (Linux, advanced)
      --binary    override the binary path baked into the unit
```

--------------------------------

### 200 OK Response Example

Source: https://docs.runwisp.com/api/operations/gettasks

An example of a successful response (200 OK) when listing tasks. The response is a JSON array containing task configurations.

```json
[
  {
    "catch_up": "latest",
    "kind": "task",
    "log_on_full": "drop_new",
    "on_overlap": "queue",
    "restart": "never",
    "restart_backoff": "constant",
    "retry_backoff": "constant"
  }
]
```

--------------------------------

### Successful Response Example

Source: https://docs.runwisp.com/api/operations/bulkrestoreruns

This is an example of a successful response (200 OK) from the bulk restore operation. It indicates the number of affected resources.

```json
{
  "$schema": "http://localhost:9477/schemas/BulkAffectedBody.json"
}
```

--------------------------------

### Run-Lifecycle Log Examples

Source: https://docs.runwisp.com/operations/logging

These lines indicate the high-level status of tasks and runs, such as starting, succeeding, or failing. They are distinct from per-output-line capture which goes to separate log files.

```text
time=2026-05-27T14:03:01.412+02:00 level=INFO msg="run started" task=backup run=01J...
time=2026-05-27T14:03:04.918+02:00 level=INFO msg="run succeeded" task=backup run=01J... exit=0 dur=3.5s
time=2026-05-27T14:07:00.231+02:00 level=WARN msg="run failed" task=report run=01J... exit=2 reason=failed dur=412ms
```

--------------------------------

### Fetch Run Events with cURL

Source: https://docs.runwisp.com/api/operations/streamruns

Use cURL to fetch run lifecycle events. This command-line example shows how to make a simple GET request to the streaming endpoint.

```curl
curl --request GET \
  --url http://localhost:9477/api/runs/stream
```

--------------------------------

### Queue Concurrency Policy Example

Source: https://docs.runwisp.com/concepts/concurrency

Use the 'queue' policy when every task tick must eventually run. New runs are added to a FIFO queue and start when a slot becomes available. This is suitable for tasks where skipping a tick means missing real work.

```toml
[tasks.process-uploads]
cron       = "*/5 * * * *"
on_overlap = "queue"          # default — could be omitted
run        = "/usr/local/bin/process"

```

--------------------------------

### Example Success Response (200 OK)

Source: https://docs.runwisp.com/api/operations/getallruns

Illustrates the structure of a successful response when listing runs. This example shows a pending run triggered by a cron job.

```json
{
  "$schema": "http://localhost:9477/schemas/RunsResponseBody.json",
  "runs": [
    {
      "$schema": "http://localhost:9477/schemas/Run.json",
      "end_reason": "success",
      "status": "pending",
      "triggered_by": "cron"
    }
  ]
}
```

--------------------------------

### 200 OK Response Example

Source: https://docs.runwisp.com/api/operations/getrunsummary

This is an example of a successful response (200 OK) from the /api/runs/summary endpoint. It indicates the structure of the returned run statistics.

```json
{
  "$schema": "http://localhost:9477/schemas/RunSummary.json"
}
```

--------------------------------

### Example 200 OK Response

Source: https://docs.runwisp.com/api/operations/getinfo

This is an example of a successful response (200 OK) from the /api/info endpoint. It includes details about the daemon's schema, tasks, and timezone configuration.

```json
{
  "$schema": "http://localhost:9477/schemas/DaemonInfo.json",
  "tasks": [
    {
      "kind": "task"
    }
  ],
  "timezone_source": "config"
}
```

--------------------------------

### Install RunWisp Service with Print Option

Source: https://docs.runwisp.com/operations/autostart

Installs the RunWisp service by printing the rendered unit file to stdout without modifying the filesystem. This is useful for automation with tools like Ansible or Nix. It allows specifying binary, config, data paths, and network settings.

```bash
runwisp service install --print \
  --binary /opt/runwisp/bin/runwisp \
  --config /etc/runwisp/runwisp.toml \
  --data /var/lib/runwisp \
  --port 9477 --host 127.0.0.1 > /etc/systemd/system/runwisp-bright-falcon.service
```

--------------------------------

### Fetch Run Events with JavaScript

Source: https://docs.runwisp.com/api/operations/streamruns

Use the fetch API in JavaScript to stream run lifecycle events. This example demonstrates making a GET request and processing the JSON response.

```javascript
const url = 'http://localhost:9477/api/runs/stream';
const options = {method: 'GET'};


try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

--------------------------------

### Example 200 Response

Source: https://docs.runwisp.com/api/operations/getrun

This is an example of a successful (200 OK) response when retrieving run details. It includes fields like $schema, end_reason, status, and triggered_by.

```json
{
  "$schema": "http://localhost:9477/schemas/Run.json",
  "end_reason": "success",
  "status": "pending",
  "triggered_by": "cron"
}
```

--------------------------------

### Example Success Response

Source: https://docs.runwisp.com/api/operations/getlocalcredentials

This is an example of a successful JSON response when retrieving local credentials. It includes the schema URL and indicates that the password is ephemeral.

```json
{
  "$schema": "http://localhost:9477/schemas/LocalCredentialsBody.json"
}
```

--------------------------------

### Example 200 OK Response

Source: https://docs.runwisp.com/api/operations/getsystemstats

This is an example of a successful response (200 OK) from the /api/system endpoint. It includes the schema URL for the system statistics object.

```json
{
  "$schema": "http://localhost:9477/schemas/SystemStats.json"
}
```

--------------------------------

### Build RunWisp from source

Source: https://docs.runwisp.com/getting-started/quick-start

Clone the RunWisp repository and use Bun to install dependencies and build the project. Requires Go 1.25+ and Bun.

```shell
git clone https://github.com/runwisp/runwisp
cd runwisp
bun install
bun run build
```

--------------------------------

### Start RunWisp daemon

Source: https://docs.runwisp.com/getting-started/quick-start

Use this command to start the RunWisp daemon in environments without a terminal, such as cron, systemd, or Docker. It will exit with an error if no configuration file is found.

```shell
runwisp daemon
```

--------------------------------

### JavaScript Fetch API Example

Source: https://docs.runwisp.com/api/operations/bulkrerunruns

Demonstrates how to re-run tasks using the fetch API in JavaScript. This example shows how to construct the request with specific IDs, filters, and matching options.

```javascript
const url = 'http://localhost:9477/api/runs/bulk/rerun';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"except_ids":["example"],"filter":{"search":"example","status":"example","task_name":"example"},"ids":["example"],"match_all":true}'
};


try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

--------------------------------

### Successful Response Example

Source: https://docs.runwisp.com/api/operations/bulkrerunruns

Example of a successful response (200 OK) when re-running tasks. It includes the schema URL and details about the newly triggered runs.

```json
{
  "$schema": "http://localhost:9477/schemas/BulkRerunBody.json"
}
```

--------------------------------

### Run Started Event

Source: https://docs.runwisp.com/api/operations/streamruns

This endpoint allows you to receive notifications when a run starts. It requires the event name and provides details about the run.

```APIDOC
## POST /websites/{website_id}/stream/runs

### Description
This endpoint is used to stream run events, specifically when a run is started.

### Method
POST

### Endpoint
`/websites/{website_id}/stream/runs`

### Parameters
#### Request Body
- **event** (string) - Required - The event name. Allowed value: `run.started`
- **id** (integer) - Optional - The event ID.
- **retry** (integer) - Optional - The retry time in milliseconds.

### Response
#### Success Response (200)
- **data** (object) - Required - Contains the run details.
  - **$schema** (string) - Optional - A URL to the JSON Schema for this object.
  - **created_at** (string) - Required - Timestamp when the run was created (format: date-time).
  - **end_at** (string) - Optional - Timestamp when the run ended (format: date-time).
  - **end_reason** (string) - Optional - Reason why a run ended. Set when status=ended. Allowed values: `success`, `failed`, `stopped`, `timeout`, `crashed`, `skipped`, `log_overflow`, `queue_full`, `dst_skipped`, `daemon_stopped`.
  - **exit_code** (integer) - Required - The exit code of the run (format: int64).
  - **external_execution_id** (string) - Optional - The external execution ID.
  - **id** (string) - Required - The unique identifier for the run.
  - **instance_index** (integer) - Required - The index of the instance running the task (format: int64).
  - **retry_attempt** (integer) - Required - The number of retry attempts made (format: int64).
  - **retry_of_run_id** (string) - Optional - The ID of the run that was retried.
  - **start_at** (string) - Optional - Timestamp when the run started (format: date-time).
  - **status** (string) - Required - The current status of the run. Allowed values: `pending`, `running`, `ended`.
  - **task_name** (string) - Required - The name of the task.
  - **triggered_by** (string) - Required - How the run was triggered. Allowed values: `cron`, `api`, `cloud`, `service`.
- **error** (string) - Optional - An error message if the event processing failed.
- **run** (object) - Required - Details of the run.
  - **$schema** (string) - Optional - A URL to the JSON Schema for this object.
  - **created_at** (string) - Required - Timestamp when the run was created (format: date-time).
  - **end_at** (string) - Optional - Timestamp when the run ended (format: date-time).
  - **end_reason** (string) - Optional - Reason why a run ended. Set when status=ended. Allowed values: `success`, `failed`, `stopped`, `timeout`, `crashed`, `skipped`, `log_overflow`, `queue_full`, `dst_skipped`, `daemon_stopped`.
  - **exit_code** (integer) - Required - The exit code of the run (format: int64).
  - **external_execution_id** (string) - Optional - The external execution ID.
  - **id** (string) - Required - The unique identifier for the run.
  - **instance_index** (integer) - Required - The index of the instance running the task (format: int64).
  - **retry_attempt** (integer) - Required - The number of retry attempts made (format: int64).
  - **retry_of_run_id** (string) - Optional - The ID of the run that was retried.
  - **start_at** (string) - Optional - Timestamp when the run started (format: date-time).
  - **status** (string) - Required - The current status of the run. Allowed values: `pending`, `running`, `ended`.
  - **task_name** (string) - Required - The name of the task.
  - **triggered_by** (string) - Required - How the run was triggered. Allowed values: `cron`, `api`, `cloud`, `service`.

### Request Example
```json
{
  "event": "run.started",
  "id": 123,
  "retry": 5000
}
```

### Response Example
```json
{
  "data": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "created_at": "2023-10-27T10:00:00Z",
    "exit_code": 0,
    "id": "run-abc123xyz",
    "instance_index": 0,
    "retry_attempt": 0,
    "start_at": "2023-10-27T10:00:05Z",
    "status": "running",
    "task_name": "my-task",
    "triggered_by": "api"
  },
  "run": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "created_at": "2023-10-27T10:00:00Z",
    "exit_code": 0,
    "id": "run-abc123xyz",
    "instance_index": 0,
    "retry_attempt": 0,
    "start_at": "2023-10-27T10:00:05Z",
    "status": "running",
    "task_name": "my-task",
    "triggered_by": "api"
  }
}
```
```

--------------------------------

### Daemon Configuration Settings

Source: https://docs.runwisp.com/configuration/daemon

Example of the [daemon] section in the configuration file. This section is optional and controls global daemon settings.

```ini
[daemon]
shutdown_timeout = "10s"
external_url     = "https://runwisp.example.com"
metrics_enabled  = false
metrics_listen   = ""

```

--------------------------------

### 200 OK Response Example

Source: https://docs.runwisp.com/api/operations/listnotifications

This is an example of a successful response (200 OK) when listing notifications. It shows the basic structure of the response body, including the schema URL.

```json
{
  "$schema": "http://localhost:9477/schemas/NotificationsListBody.json"
}
```

--------------------------------

### Example 200 OK Response for Historical Metrics

Source: https://docs.runwisp.com/api/operations/getmetricshistory

This is an example of a successful response (200 OK) when retrieving historical system metrics. The response is an array of objects, each containing CPU usage, memory usage, total memory, used memory, and a timestamp.

```json
[
  {
    "cpu": 1,
    "mem": 1,
    "mem_total": 1,
    "mem_used": 1,
    "ts": 1
  }
]
```

--------------------------------

### Successful Response Example (200 OK)

Source: https://docs.runwisp.com/api/operations/getunreadnotificationcount

This is an example of a successful response when retrieving the unread notification count. The response includes a schema URL and the actual count of unread notifications.

```json
{
  "$schema": "http://localhost:9477/schemas/NotificationUnreadBody.json"
}
```

--------------------------------

### Example Default Error Response

Source: https://docs.runwisp.com/api/operations/getsystemstats

This example illustrates a default error response from the API. It follows the Problem Details specification and includes fields like 'detail', 'instance', 'status', 'title', and 'type'.

```json
{
  "$schema": "http://localhost:9477/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}
```

--------------------------------

### Cron Expression Examples

Source: https://docs.runwisp.com/concepts/scheduling

Illustrates various cron expressions and their meanings, from every minute to specific times and intervals.

```text
Expression| Meaning  
---|---
`* * * * *`| every minute  
`*/5 * * * *`| every 5 minutes  
`0 * * * *`| top of every hour  
`0 2 * * *`| every day at 02:00  
`30 9 * * 1-5`| weekdays at 09:30  
`0 0 1 * *`| first of every month at midnight  
`@hourly`| top of every hour  
`@daily` / `@midnight`| every day at 00:00  
`@weekly`| Sundays at 00:00  
`@monthly`| 1st at 00:00  
`@yearly` / `@annually`| January 1st at 00:00  
`@every 1h30m`| every 90 minutes  
```

--------------------------------

### Fetch Log Lines with JavaScript

Source: https://docs.runwisp.com/api/operations/searchlogs

Use the fetch API in JavaScript to retrieve log lines from a task. This example demonstrates making a GET request and handling the JSON response.

```javascript
const url = 'http://localhost:9477/api/tasks/example/log/search';
const options = {method: 'GET'};


try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

--------------------------------

### Manual installation from GitHub releases

Source: https://docs.runwisp.com/getting-started/quick-start

Download the appropriate tarball from GitHub releases, extract it, and move the binary to your system's PATH. Verify the download using the provided checksums.

```shell
tar -xzf runwisp-linux-x64.tar.gz
sudo mv runwisp /usr/local/bin/runwisp
```

--------------------------------

### Terminate Concurrency Policy Example

Source: https://docs.runwisp.com/concepts/concurrency

Utilize the 'terminate' policy when the newest task run is the most important. RunWisp stops the oldest active run, allowing the new one to start. This is best for tasks where the latest execution supersedes any previous ones, such as deploy hooks.

```toml
[tasks.deploy-hook]
on_overlap = "terminate"
run        = "/usr/local/bin/deploy.sh"

```

--------------------------------

### Initialize RunWisp in a directory

Source: https://docs.runwisp.com/getting-started/quick-start

Run this command in a directory to start RunWisp. If no configuration file exists, it will prompt to create a starter file and launch the TUI.

```shell
runwisp
```

--------------------------------

### Run RunWisp using Bun (npx equivalent)

Source: https://docs.runwisp.com/getting-started/quick-start

Use this command to try RunWisp without a global installation, suitable for temporary environments or CI runners.

```shell
bunx runwisp
```

--------------------------------

### Fetch JavaScript Example

Source: https://docs.runwisp.com/api/operations/gettasks

Demonstrates how to fetch all tasks using the JavaScript Fetch API. Ensure the URL and options are correctly configured for your environment.

```javascript
const url = 'http://localhost:9477/api/tasks';
const options = {method: 'GET'};


try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

--------------------------------

### GET /api/system

Source: https://docs.runwisp.com/api

Gets the current system status. This endpoint provides an overview of the system's operational state.

```APIDOC
## GET /api/system

### Description
Gets the current system status.

### Method
GET

### Endpoint
/api/system
```

--------------------------------

### Install RunWisp using curl

Source: https://docs.runwisp.com/getting-started/quick-start

This command automatically detects your OS and architecture, downloads the correct release, verifies its integrity, and places the runwisp binary in your PATH.

```shell
curl -fsSL https://get.runwisp.com | sh
```

--------------------------------

### Starting the RunWisp TUI

Source: https://docs.runwisp.com/getting-started/tui-tour

Two primary commands to launch the TUI. The first attaches to the local daemon, while the second attaches a fresh TUI to an already running daemon, optionally specifying a remote host.

```bash
runwisp           # spawn or attach to the local daemon, then attach the TUI
runwisp tui       # attach a fresh TUI to an already-running daemon
```

--------------------------------

### GET /api/tasks/{taskName}/runs/{runId}

Source: https://docs.runwisp.com/api

Retrieves details of a specific run for a task. Get in-depth information about a particular execution instance.

```APIDOC
## GET /api/tasks/{taskName}/runs/{runId}

### Description
Retrieves details of a specific run for a task.

### Method
GET

### Endpoint
/api/tasks/{taskName}/runs/{runId}

### Parameters
#### Path Parameters
- **taskName** (string) - Required - The name of the task.
- **runId** (string) - Required - The ID of the run.
```

--------------------------------

### Environment and File Substitution in TOML

Source: https://docs.runwisp.com/configuration/substitution

Demonstrates using environment variables and file contents for task cron schedules, descriptions, and notifier webhook URLs.

```toml
[tasks.backup]
cron        = "${BACKUP_CRON}"          # from the daemon's environment
description = "backs up ${REGION}"      # works mid-string too
run         = "/usr/local/bin/backup.sh"

[[notifier]]
id          = "slack-ops"
type        = "slack"
webhook_url = "${file:secrets/slack.url}"   # from a file
```

--------------------------------

### GET /api/tasks/{taskName}/runs/{runId}/log

Source: https://docs.runwisp.com/api

Retrieves the logs for a specific run of a task. Get detailed logs associated with a particular execution.

```APIDOC
## GET /api/tasks/{taskName}/runs/{runId}/log

### Description
Retrieves the logs for a specific run of a task.

### Method
GET

### Endpoint
/api/tasks/{taskName}/runs/{runId}/log

### Parameters
#### Path Parameters
- **taskName** (string) - Required - The name of the task.
- **runId** (string) - Required - The ID of the run whose logs are to be retrieved.
```

--------------------------------

### JSON Log Output Example

Source: https://docs.runwisp.com/operations/logging

An example of a single log line formatted as a JSON object when `--log-format=json` is used. This format is ideal for machine parsing.

```json
{
    "time": "2026-05-27T14:03:04.918+02:00",
    "level": "INFO",
    "msg": "run succeeded",
    "task": "backup",
    "run": "01J...",
    "exit": 0,
    "dur": 3500000000
}
```

--------------------------------

### Run RunWisp using npm (npx equivalent)

Source: https://docs.runwisp.com/getting-started/quick-start

Use this command to try RunWisp without a global installation, suitable for temporary environments or CI runners.

```shell
npx runwisp
```

--------------------------------

### Log Search Response Schema Example

Source: https://docs.runwisp.com/api/operations/searchlogs

An example of the JSON schema for a successful log search response. This schema defines the structure of the data returned by the API.

```json
{
  "$schema": "http://localhost:9477/schemas/LogSearchBody.json"
}
```

--------------------------------

### GitHub Actions Deploy Step

Source: https://docs.runwisp.com/recipes/deploy-hooks

Example of a GitHub Actions step to trigger a deploy using a local runwisp-trigger.sh script. It shows how to set environment variables for authentication.

```yaml
- name: Deploy to production
  env:
      RUNWISP_PASSWORD: ${{ secrets.RUNWISP_PASSWORD }}
  run: ./bin/runwisp-trigger.sh deploy-app
```

--------------------------------

### Successful Log Page Response Example

Source: https://docs.runwisp.com/api/operations/getlogpage

An example of a successful JSON response from the log page API. It includes the schema URL and indicates the status of the log data.

```json
{
  "$schema": "http://localhost:9477/schemas/LogPageBody.json"
}
```

--------------------------------

### Enable Metrics in runwisp.toml

Source: https://docs.runwisp.com/operations/metrics

Add this configuration to your runwisp.toml file and restart the daemon to enable metrics.

```toml
[daemon]
metrics_enabled = true

```

--------------------------------

### Run Service from Docker Compose

Source: https://docs.runwisp.com/configuration/services

Configure a service to run using an existing Docker Compose file. Optionally specify the compose service name; defaults to the table key.

```TOML
[services.api]
compose_file    = "./docker-compose.yml"
compose_service = "api"
notify_on_failure = ["slack-prod"]

```

--------------------------------

### Full Compose Configuration Options

Source: https://docs.runwisp.com/configuration/compose

This snippet demonstrates the extensive configuration options available for a compose block, including file path, service inclusion/exclusion, mode, grouping, and more.

```TOML
[compose.myapp]
file         = "./docker-compose.yml"   # default: auto-discovered next to runwisp.toml
include      = ["api", "worker"]         # subset; omit to import all
exclude      = ["db"]                    # mutually exclusive with include
mode         = "services"                # "services" (default) | "stack"
group        = "myapp"                   # UI group; defaults to the alias
project_name = "myapp"                   # docker compose -p; defaults to the alias
profiles     = ["production"]            # docker compose --profile
env_file     = ["./.env.prod"]           # docker compose --env-file
working_dir  = "/opt/myapp"              # cwd for compose invocation; defaults to dir of `file`
with_deps    = false                     # default: --no-deps; true starts compose deps too
pull         = "missing"                 # "missing" (default) | "always" | "never"
name_format  = "{alias}.{service}"       # RunWisp task naming; default shown

```

--------------------------------

### Get Unread Notification Count with JavaScript

Source: https://docs.runwisp.com/api/operations/getunreadnotificationcount

Use this JavaScript snippet to make a GET request to the unread count endpoint and log the response. Ensure you handle potential errors during the fetch operation.

```javascript
const url = 'http://localhost:9477/api/notifications/unread-count';
const options = {method: 'GET'};


try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

--------------------------------

### Per-Service Overrides for Compose Services

Source: https://docs.runwisp.com/configuration/compose

This example shows how to apply specific RunWisp configurations to individual services defined within a docker-compose.yml file. Overrides can include restart policies, notification settings, and environment variables.

```TOML
[compose.myapp]
file = "./docker-compose.yml"


[compose.myapp.api]
restart           = "always"
notify_on_failure = ["slack-prod"]
graceful_stop     = "30s"
keep_runs         = 100
env               = { LOG_LEVEL = "info" }  # merged on top of compose env


[compose.myapp.worker]
restart   = "on_failure"
instances = 3                              # three identical worker instances

```

--------------------------------

### Restart Service using cURL

Source: https://docs.runwisp.com/api/operations/restartservice

This cURL command demonstrates how to restart a service instance from the command line. Ensure you replace 'example' with your actual task name.

```curl
curl --request POST \
  --url http://localhost:9477/api/tasks/example/restart
```

--------------------------------

### Define a Service with Multiple Instances

Source: https://docs.runwisp.com/concepts/tasks-vs-services

Use the `[services.<name>]` header for processes that should remain running. The `instances` field specifies how many replicas of the service should be active.

```yaml
[services.api-worker]
instances = 3
run       = "/usr/local/bin/worker"

```

--------------------------------

### Shell Expansion for Task 'run' Command

Source: https://docs.runwisp.com/configuration/substitution

Shows how the `run` command in tasks is not substituted by RunWisp but by the shell, allowing for dynamic environment variable expansion.

```toml
[tasks.backup]
run = "backup.sh --bucket ${BACKUP_BUCKET}"   # the shell expands this, not RunWisp

[tasks.backup.env]
BACKUP_BUCKET = "s3://prod-backups"
```

--------------------------------

### Get System Statistics

Source: https://docs.runwisp.com/api/operations/getsystemstats

Fetches system statistics from the RunWisp daemon.

```APIDOC
## GET /api/system

### Description
Retrieves current statistics about the system where the RunWisp daemon is running.

### Method
GET

### Endpoint
/api/system

### Responses
#### Success Response (200)
- **$schema** (string) - A URL to the JSON Schema for this object.
- **arch** (string) - Required - CPU architecture (e.g. amd64, arm64).
- **cpu_cores** (integer) - Required - Number of CPU cores.
- **cpu_usage** (number) - Required - CPU usage percentage (0-100).
- **host** (string) - Required - Hostname.
- **mem_total** (integer) - Required - Total memory in bytes.
- **mem_usage** (number) - Required - Memory usage percentage (0-100).
- **mem_used** (integer) - Required - Used memory in bytes.
- **name** (string) - Required - Application name.
- **os** (string) - Required - Operating system (e.g. linux, darwin, windows).
- **uptime** (string) - Required - Human-readable uptime.
- **version** (string) - Required - RunWisp version.
- **work_dir** (string) - Required - Working directory of the daemon process.

#### Response Example (200)
```json
{
  "$schema": "http://localhost:9477/schemas/SystemStats.json"
}
```

#### Error Response (default)
- **$schema** (string) - A URL to the JSON Schema for this object.
- **detail** (string) - A human-readable explanation specific to this occurrence of the problem.
- **errors** (array | null) - Optional list of individual error details.
  - **location** (string) - Where the error occurred, e.g. ‘body.items[3].tags’ or ‘path.thing-id’.
  - **message** (string) - Error message text.
  - **value** (any) - The value at the given location.
- **instance** (string) - A URI reference that identifies the specific occurrence of the problem.
- **status** (integer) - HTTP status code.
- **title** (string) - A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
- **type** (string) - A URI reference to human-readable documentation for the error.

#### Response Example (default)
```json
{
  "$schema": "http://localhost:9477/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}
```
```

--------------------------------

### GET /api/runs/stream

Source: https://docs.runwisp.com/api

Streams real-time updates for runs. Monitor the status of runs as they progress.

```APIDOC
## GET /api/runs/stream

### Description
Streams real-time updates for runs.

### Method
GET

### Endpoint
/api/runs/stream
```

--------------------------------

### GET /api/runs

Source: https://docs.runwisp.com/api

Retrieves a list of all runs. This endpoint provides an overview of all execution instances.

```APIDOC
## GET /api/runs

### Description
Retrieves a list of all runs.

### Method
GET

### Endpoint
/api/runs
```

--------------------------------

### Fetch Log as Text (cURL)

Source: https://docs.runwisp.com/api/operations/getlograw

This cURL command demonstrates how to fetch the raw log content from the API. Replace the example URL with your actual endpoint.

```curl
curl --request GET \
  --url http://localhost:9477/api/tasks/example/runs/example/log/raw
```

--------------------------------

### GET /api/runs/summary

Source: https://docs.runwisp.com/api

Retrieves a summary of all runs. This endpoint provides aggregated statistics and status overviews.

```APIDOC
## GET /api/runs/summary

### Description
Retrieves a summary of all runs.

### Method
GET

### Endpoint
/api/runs/summary
```

--------------------------------

### Task Configuration Example

Source: https://docs.runwisp.com/configuration/tasks

Defines a task to drain a queue every 10 minutes with specific retry and notification settings. Use this for background jobs requiring scheduled execution and robust error handling.

```toml
[tasks.process-event-queue]
group          = "Workers"
description    = "Drain the queue every 10 minutes with retries"
cron           = "*/10 * * * *"
on_overlap     = "skip"           # never two queue drainers at once
timeout        = "9m"             # die before the next firing
graceful_stop  = "30s"            # this drainer needs more than the 5s default
retry_attempts = 3
retry_delay    = "2s"
retry_backoff  = "exponential"
keep_runs      = 200
keep_for       = "14d"
notify_on_failure = ["slack-ops"]
run = """
set -eu
trap 'echo "draining gracefully"; /usr/local/bin/process-queue --drain' TERM
echo "Draining queue at $(date -Iseconds)"
/usr/local/bin/process-queue
""

```