# Routines

Saved prompts with schedule or API triggers, scoped per project. Source: packages/nikcli/src/cli/cmd/routine.ts.

## What Are Routines

A routine pairs a saved prompt with one or more triggers. When a trigger fires, nikcli runs the prompt as a background session and records the resulting session ID. Routines are scoped to the current project directory — each project has its own routine list.

Two trigger types are supported:

-   **schedule** — a cron expression that fires the routine on a timer.
-   **api** — a secret token that lets external systems trigger the routine via HTTP.

A single routine can have both a schedule trigger and an API trigger at the same time.

## Triggers

### Schedule trigger

The schedule trigger accepts the following cron patterns:

| Pattern | Meaning |
| --- | --- |
| `@hourly` | Once per hour. |
| `@daily` | Once per day. |
| `@weekly` | Once per week. |
| `*/N` | Every N minutes (e.g. `*/30` = every 30 minutes). |
| `0 */N * * *` | Every N hours (e.g. `0 */6 * * *` = every 6 hours). |

Unrecognised cron patterns

If the cron pattern you supply does not match one of the supported forms above, the routine is created and saved but the schedule will **not** fire. nikcli prints a warning at creation time and the trigger is stored as-is. You can still run the routine manually with `nikcli routine run <id>`.

### API trigger

API triggers attach a secret token to the routine. Any system that can make an HTTP POST request can fire the routine without needing direct access to the machine running nikcli.

Terminal

bash 

```
POST /mobile/routines/trigger/<token>
```

$ shell · paste into your terminal

The token is generated automatically when you pass `--api` to `routine create`, or you can supply your own with `--api-token`. nikcli prints the full endpoint URL after the routine is created.

## Subcommands

| Subcommand | Alias | Purpose |
| --- | --- | --- |
| `routine list` | `ls` | List all routines for the current project. Accepts `--format table|json`. |
| `routine create` | — | Create a routine interactively or via flags. See flags below. |
| `routine get <id>` | — | Show full details of a routine. Accepts `--format text|json`. |
| `routine run <id>` | — | Trigger an immediate run. Accepts `--text` to append one-off context to this run. |
| `routine pause <id>` | — | Pause the routine; disables all scheduled triggers until resumed. |
| `routine resume <id>` | — | Resume a paused routine and re-enable its triggers. |
| `routine delete <id>` | `rm` | Delete the routine. Prompts for confirmation unless `--yes` / `-y` is passed. |

## Creating a Routine

Run `nikcli routine create` without flags to go through an interactive prompt for name, prompt, and cron schedule. Pass flags to skip the interactive steps:

| Flag | Alias | Description |
| --- | --- | --- |
| `--name` | `-n` | Routine name. |
| `--prompt` | `-p` | Prompt text to run. |
| `--cron` | — | Cron schedule expression (see supported patterns above). |
| `--api` | — | Enable an API trigger with a randomly generated token. |
| `--api-token` | — | Enable an API trigger with a specific custom token. |

Terminal

bash 

```
# Interactive creation
      nikcli routine create

      # Fully scripted — daily schedule + API trigger
      nikcli routine create \
        --name "daily-review" \
        --prompt "Review recent changes and summarize any risks." \
        --cron @daily \
        --api

      # Every 30 minutes, custom API token
      nikcli routine create \
        --name "health-check" \
        --prompt "Run the test suite and report failures." \
        --cron "*/30" \
        --api-token "my-secret-token"
```

$ shell · paste into your terminal

## API Trigger

After creating a routine with `--api` or `--api-token`, nikcli prints the trigger endpoint. Fire it from any HTTP client:

Terminal

bash 

```
# Trigger a routine from a CI pipeline or webhook
      curl -X POST https://your-host/mobile/routines/trigger/nkr_abc123...

      # View the token again
      nikcli routine get <id>
```

$ shell · paste into your terminal

Token prefix

Automatically generated tokens start with `nkr_` followed by 64 hex characters. Custom tokens passed via `--api-token` are stored as-is.

## Lifecycle

A routine moves through the following states:

| State | Meaning |
| --- | --- |
| `active` | Triggers are enabled and will fire on schedule or API call. |
| `paused` | Triggers are disabled. The routine can still be run manually with `routine run`. |

Terminal

bash 

```
nikcli routine list
      nikcli routine pause rtn_abc123
      nikcli routine resume rtn_abc123
      nikcli routine run rtn_abc123 --text "focus on the auth module"
      nikcli routine delete rtn_abc123 --yes
```

$ shell · paste into your terminal

---

Source: https://nikcli-ai.dev/docs/routines