Documentation

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>

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"

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>

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