Scheduled automations
Nethür automations run a prompt on a schedule from the CLI, so recurring triage, review, and maintenance tasks can start without you opening a worktree by hand. By the end of this page, you'll create a disabled automation, inspect it, and run it when you're ready.
Create a safe first automation
Start with --disabled while you tune the prompt and target:
nethur automations create \
--name "Weekday triage" \
--trigger weekdays \
--time 09:00 \
--prompt "Triage new issues and summarize blockers" \
--provider codex \
--repo my-repo \
--disabled \
--json--trigger accepts presets such as hourly, daily, weekdays, and weekly, plus cron expressions or RRULE strings. Use --timezone <tz> when the schedule should follow a specific IANA timezone instead of the runtime default.
Choose where runs happen
Use --repo <selector> when each run should create or select work in a repository. Use --workspace <selector> when the automation should run inside an existing Nethür worktree instead:
nethur automations create \
--name "Nightly status" \
--trigger "0 18 * * 1-5" \
--prompt "Summarize today's changes" \
--provider claude \
--workspace active \
--disabledWhen you omit both target flags, Nethür resolves the enclosing worktree from the current shell directory when it can.
Precheck before a run
Skip scheduled work when a cheap shell probe fails (non-zero exit records a skipped run):
nethur automations create \
--name "PR review" \
--trigger hourly \
--precheck "gh pr list --json number -q .[0].number" \
--prompt "Review requested PRs" \
--provider codex \
--repo my-repo \
--disabled \
--jsonProject host / setup targets
When the automation should run on a specific project host setup rather than only --repo / --workspace:
nethur automations create \
--name "Remote triage" \
--trigger daily \
--time 09:00 \
--prompt "Triage open issues" \
--provider claude \
--project <projectId> \
--host <host> \
--disabled \
--json--project takes the project id or the display name from nethur project list. --host takes local, ssh:<target-id>, runtime:<environment-id>, or the bare name from nethur host list, and it can be omitted entirely when the project is set up on only one host — Nethür uses that one. When the project is set up on several, the error names each host and the flag to select it.
Use --project-host-setup <id> when you already have a setup id. Optional --source-context '<json>' pins task/provider data to a host/account (pass null on edit to clear).
Manage automations across hosts
The desktop Automations page loads schedules from this computer and supported connected Nethür hosts into one table. The Host column shows where each automation is stored and scheduled; use Filters → Host to show one or more hosts, or return to All hosts.
When you create an automation in the desktop UI, Create on chooses its host before you choose a project. The project picker then shows projects available on that destination. Connected hosts that need a newer Nethür server stay visible but disabled, with an Update server message, instead of disappearing from the picker.
Missed-run grace
nethur automations edit <automationId> --missed-run-grace-minutes 30 --jsonReuse an existing automation session
For automations that target an existing worktree, add --reuse-session when later runs should continue in the previous live automation terminal instead of starting from a blank terminal each time:
nethur automations create \
--name "Inbox digest" \
--trigger hourly \
--prompt "Summarize unread mail" \
--provider codex \
--workspace active \
--reuse-session \
--disabledUse nethur automations edit <automationId> --fresh-session --json to switch the automation back to a fresh terminal per run.
Extra agent arguments
Add arguments to the agent command for one automation, for example a different model:
nethur automations create \
--name "Docs pass" \
--trigger daily \
--prompt "Tidy the docs" \
--provider claude \
--extra-agent-args="--model opus --add-dir docs"On each fresh run, Nethür starts from the host's default Arguments for that agent and appends the extras. A model or effort option in the extras replaces the one in the defaults. Pass the value with = because it starts with --.
Saved extras use the same quoting on every host, including Windows: wrap values containing spaces in single or double quotes, and use single quotes to preserve backslashes in paths, such as --add-dir 'C:\work\my docs'. Nethür passes these as literal arguments; shell commands and expansions are not supported.
Extras accept only model and effort options, plus Claude's --add-dir, for Claude, Codex, CodeBuddy, Cursor, Grok, and OMP. Permission, config, prompt, and session options are rejected. Extras require a fresh session for every run, so they can't be combined with --reuse-session. Use nethur automations edit <automationId> --extra-agent-args= to clear them.
Review and enable
List and inspect automations before enabling them:
nethur automations list --json
nethur automations show <automationId> --json
nethur automations edit <automationId> --enabled --jsonIn the desktop automations list, use the search field to filter by name, project, or prompt text when you have many schedules.
Use Filters to narrow the list by Host, Enabled or Paused state, last-run outcome (Failed, Succeeded, or Never ran), or one or more Agents. Search inside the agent submenu when the list is long; active filters appear as removable pills above the table. The table shows the host, last-run result, and relative time for each automation. Click the Name or Last run column to sort; name sorts alphabetically, while last run defaults to newest first.
When the automation list is open, type in the search field and press ArrowUp or ArrowDown to move the selection through the visible matching rows. The list keeps the selected row in view; modified or composing input keeps its normal cursor behavior.
Use edit to change the name, prompt, provider, target, schedule, or enabled state. remove deletes an automation and its run history.
Run on demand
After creating an automation, trigger it manually to check the prompt and target before waiting for the next scheduled time:
nethur automations run <automationId> --json
nethur automations runs --id <automationId> --jsonIf a run fails before it opens a workspace or reconnects to its target, open that run in Nethür and click Rerun to queue a fresh manual run for the same automation.
Next steps
- Nethür CLI overview — see the rest of the CLI surface for worktrees, terminals, and browser control.
- Skills registry & MCP — install the Nethür CLI skill so agents can call the same commands.