Nethür CLI reference

Commands, selectors, and agent-friendly patterns for driving Nethür from a shell.

The nethur CLI talks to a running Nethür runtime. Use it when a shell script or agent needs to inspect worktrees, launch terminals, open files, automate the built-in browser, or report progress back into Nethür.

Verify the runtime

Register the CLI under Settings → General → Nethür CLI, then check that it can reach Nethür.

On macOS and Windows:

bash
command -v nethur
nethur status --json

On Linux:

bash
command -v nethur-ide
nethur-ide status --json

If Nethür is not already running:

bash
nethur open --json
nethur status --json

Use --json when another tool will parse the result. Human-readable output is for quick terminal checks.

Selectors

Most commands accept selectors instead of requiring long IDs:

bash
nethur repo show --repo id:<repoId> --json
nethur worktree show --worktree active --json
nethur worktree show --worktree path:/abs/path/to/worktree --json
nethur worktree show --worktree branch:feature-name --json
nethur worktree show --worktree issue:123 --json

active and current resolve to the enclosing Nethür-managed worktree from the shell's current directory or terminal context. Use explicit selectors in scripts that may run outside the target worktree. For remote runtimes, prefer full server-side selectors such as id:<repoId>::<absolute-worktree-path> or path:<absolute-server-path> because the local shell's current directory may not exist on the runtime host.

Choose a host

List every machine the current Nethür host can target and the selector for each one:

bash
nethur host list --json

The result includes this machine, its registered SSH targets, and paired Remote Nethür Servers. Use --host local for this machine, --host ssh:<target-id> for an SSH target, and --environment <server-name> for a paired server. SSH rows include the detected remote platform (linux, darwin, or win32) after the target connects; older or disconnected targets report platform unknown. They also include connected and, when known, the SSH lifecycle connectionStatus. If you put a machine name on the wrong selector, Nethür reports the matching machine and the flag to use instead of returning an empty result.

--host also takes the bare name shown in the name column, on either axis — --host trader-local reaches the same machine as --host ssh:ssh-1783599077486-fyasux. Names resolve only when they are unique: a name held by two SSH targets, by two paired servers, or by one of each is refused, and the error hands back the id form for each candidate — --host ssh:<target-id> for an SSH target and --host runtime:<environment-id> for a paired server. Use those to settle it, since --environment <server-name> cannot separate two servers sharing a name.

Runtime commands

bash
nethur open --json
nethur status --json
nethur serve --port 6768 --pairing-address 100.64.1.20 --json

nethur serve starts a runtime server in the foreground without opening the desktop window. Use it for Remote Nethür Servers or headless environments, and stop it with Ctrl-C.

Repos

bash
nethur repo list --json
nethur repo add --path /abs/path/to/repo --json
nethur repo show --repo id:<repoId> --json
nethur repo set-base-ref --repo id:<repoId> --ref origin/main --json
nethur repo search-refs --repo id:<repoId> --query main --limit 10 --json

Set the repo base ref before creating lots of worktrees so new tasks branch from the right place by default.

Worktrees

bash
nethur worktree list --repo id:<repoId> --json
nethur worktree ps --json
nethur worktree current --json
nethur worktree show --worktree active --json
nethur worktree create --repo id:<repoId> --name fix-login --json
nethur worktree create --name child-task --agent codex --prompt "Investigate the flaky login test" --json
nethur worktree set --worktree active --comment "reproduced failure; testing token refresh fix" --json
nethur worktree set --worktree active --workspace-status in-review --unread --json
nethur worktree rm --worktree id:<worktreeId> --force --json

When worktree create runs from inside an Nethür-managed worktree, Nethür records the new worktree as a child when it can infer the relationship. Pass --parent-worktree active to be explicit, or --no-parent when the new work is independent.

worktree set --unread puts the unread dot on the workspace in the sidebar, the same one Nethür shows when an agent finishes; --read clears it.

Agent startup flags:

bash
nethur worktree create --name review-api --agent claude --setup run --json
nethur worktree create --name quick-check --agent codex --prompt "Summarize the diff" --setup skip --json
nethur worktree create --name hidden-setup --setup inherit --json

--agent launches the selected agent in the first terminal. --prompt sends initial work to that agent. --setup run|skip|inherit controls repo setup hooks; inherit follows the repo policy.

Link issues and reviews using the existing workspace metadata:

bash
nethur worktree create --repo id:<repoId> --name review-task --pr 123 --json
nethur worktree create --repo id:<repoId> --name gitlab-task --gitlab-issue 42 --gitlab-mr 77 --json
nethur worktree set --worktree active --gitlab-issue '#42' --gitlab-mr '!77' --json
nethur worktree set --worktree active --gitlab-issue https://gitlab.example.com/group/project/-/work_items/42 --json
nethur worktree set --worktree active --pr null --gitlab-mr null --json

--pr is a GitHub pull request number. --gitlab-issue accepts an issue number or #42; --gitlab-mr accepts a merge request number or !77. Numbers must be positive safe integers. The GitLab flags also accept HTTP(S) issue or merge request URLs, including self-hosted instances and nested groups. The URL's host and project must match the workspace's stored GitLab source context or the repository's stored remote. If that identity is missing or different, the command fails before updating metadata. A URL cannot choose another project, change the checkout, or fetch a review branch.

Omitting a flag leaves its link unchanged. On set, literal null clears only the named link; create refuses null. Each provider has separate fields, so setting a GitLab issue or merge request preserves GitHub and Linear links.

Folder-based repositories can store numeric links through these commands, but a number does not supply a provider host or project. Without existing source context or a stored remote, pasted GitLab URLs are refused and provider details or clickable links may be unavailable. These flags use fields already supported by the runtime; an older runtime that predates a field may ignore it, so check worktree show --json after writing to an older host.

References

A workspace can link multiple reviews and issues, including sources outside its repository.

bash
nethur reference list --worktree name:api --json
nethur reference add https://github.com/acme/api/pull/5123 https://linear.app/acme/issue/STA-1234 --worktree name:api --json
nethur reference remove https://github.com/acme/api/pull/5123 --worktree name:api --json
nethur reference remove --key '<key-from-list>' --worktree name:api --json
nethur worktree create --name fix --reference https://github.com/acme/api/pull/5123 --reference https://linear.app/acme/issue/STA-1234 --json
nethur reference find STA-1234 --json
  • Writes: full URLs only; no custom shorthand. remove --key supports older entries without URLs. Source-unknown legacy links cannot match an exact URL; native issue keys remain searchable when stored. Duplicate adds and absent removals are no-ops. Unrelated links and current selection are preserved. Older hosts without safe delta merging refuse writes.
  • Create: repeat --reference; incompatible with --pr, --issue, --linear-issue, --gitlab-issue, and --gitlab-mr. References persist before setup or agent startup.
  • Find: a full URL or native issue key; bare numbers are rejected. Keys search all matching sources. Reads stored metadata, without provider requests or conversation searches. Use nethur search for conversation text.
  • Scope: --worktree selects a worktree or folder workspace. Find also accepts --repo instead, plus --include-archived and --limit (default 50 workspaces). truncated: true means more matched. Remote selectors refer to the execution host; current is local only.
  • Output: list returns references with opaque key and selected; writes also return changes. Worktree show/list/ps retain linkedItems. Find returns workspace matches and agents with linked, liveness, and available terminal/mailbox addresses. linked: false means ownership is unknown; sharing a workspace is insufficient evidence.

Choose an agent from find, then use its exact address:

bash
nethur terminal send --terminal '<terminal-from-find>' --text 'Status?' --enter
nethur orchestration send --to '<mailbox-from-find>' --subject 'Status?' --type question

Mailboxes are dispatch:<id> or nethur_session_id:<id>; a run:<id> addresses a coordinator. Find never sends messages or assigns ownership. Adding references from a shell does not associate that shell with an agent.

Terminals

bash
nethur terminal list --worktree active --json
nethur terminal show --terminal <handle> --json
nethur terminal read --terminal <handle> --json
nethur terminal read --terminal <handle> --screen --json
nethur terminal read --terminal <handle> --cursor <cursor> --limit 1000 --json
nethur terminal send --terminal <handle> --text "continue" --enter --json
nethur terminal wait --terminal <handle> --for tui-idle --timeout-ms 300000 --json
nethur terminal create --worktree active --title "tests" --command "npm test" --json
nethur terminal split --terminal <handle> --direction horizontal --command "npm run dev" --json
nethur terminal rename --terminal <handle> --title "runner" --json
nethur terminal set-pane-title --terminal <handle> --title "reviewer" --json
nethur terminal switch --terminal <handle> --json
nethur terminal close --terminal <handle> --json
nethur terminal close --worktree active --all --json

Omit --terminal to target the active terminal in the current worktree. Read before sending when you are not sure what the terminal is waiting for.

Close stops the process as part of removing the terminal. Use --terminal <handle> for one terminal, or --worktree <selector> --all to durably close every terminal in exactly that workspace, including its saved layouts and agent-resume records. Use workspace Sleep when those terminals should resume later. If the execution host cannot confirm that every PTY stopped, bulk close returns a failing unverifiable result rather than claiming the processes exited. terminal stop remains only for compatibility with older tooling.

terminal list reports each terminal's executionHostId when Nethür can verify it, plus a result-level hostScope with covered and omitted host IDs. Treat a missing host identity or scope as unverifiable, not local. A missing terminal is evidence that it exited only when its execution host is listed in hostScope.hostIds.

By default, terminal read returns the accumulated output stream with terminal escapes stripped. Programs that redraw lines can therefore appear as stacked fragments. Use --screen when you need the currently rendered frame; the response's source identifies stream, screen, or screen-unavailable. Screen reads have no history to page, so --screen and --cursor are mutually exclusive.

For long output, use cursor reads. Save nextCursor from one stream read, then pass it back with --cursor to fetch only new output.

Files

bash
nethur file open src/App.tsx --worktree active --json
nethur file open src/App.tsx --line 42 --column 7 --worktree active --focus --json
nethur file diff src/App.tsx --staged --worktree active --json
nethur file open-changed --mode both --worktree active --json

Paths are relative to the selected worktree. --line and --column are 1-based; a column requires a line. Positions are applied when you select the file, or immediately with --focus. Markdown switches to source view for positioning. Older hosts open the file without positioning. open-changed reads git status and opens changed files in edit, diff, or both modes. Tabs open without changing what you are looking at; pass --focus to be brought to them.

Built-in browser

Browser commands control Nethür's embedded browser tab for the selected worktree. They do not control Chrome, Safari, or the Nethür desktop UI.

Use a snapshot -> act -> snapshot loop:

bash
nethur goto --url http://localhost:3000 --worktree active --json
nethur snapshot --worktree active --json
nethur click --element @e3 --worktree active --json
nethur fill --element @e1 --value "[email protected]" --worktree active --json
nethur wait --text "Welcome" --worktree active --json
nethur screenshot --worktree active --json

Refs such as @e3 come from snapshot. Re-snapshot after navigation, tab switches, clicks that change the page, and any stale-ref error.

Tab and capture commands:

bash
nethur tab list --worktree active --json
nethur tab create --url http://localhost:3000 --worktree active --json
nethur tab switch --index 1 --worktree active --json
nethur capture start --worktree active --json
nethur console --limit 50 --worktree active --json
nethur network --limit 50 --worktree active --json
nethur full-screenshot --worktree active --json
nethur pdf --worktree active --json

Use nethur exec --command "<agent-browser command>" --json only for browser actions that do not have a typed Nethür command yet.

Browser device emulation:

bash
nethur set device --name "iPhone 12" --worktree active --json
nethur screenshot --worktree active --json

Desktop computer use

Use nethur computer for native desktop apps outside the built-in browser:

bash
nethur computer permissions --json
nethur computer list-apps --json
nethur computer get-app-state --app com.apple.Safari --json
nethur computer click --app com.apple.Safari --element-index 12 --json
nethur computer paste-text --app com.apple.Safari --text "hello" --json

See Computer use for the full workflow and permission setup.

Mobile emulator

The mobile emulator commands control iOS Simulator devices through Nethür's worktree-scoped bridge. Use them instead of raw serve-sim or simctl when an agent is operating from inside Nethür, so lifecycle and active-device state stay attached to the current worktree.

bash
nethur emulator list --worktree active --json
nethur emulator attach "<device-name-or-udid>" --worktree active --json
nethur emulator tap 0.5 0.7 --worktree active --json
nethur emulator type "hello" --worktree active --json
nethur emulator gesture '[{"type":"begin","x":0.5,"y":0.8},{"type":"move","x":0.5,"y":0.4},{"type":"end","x":0.5,"y":0.2}]' --worktree active --json
nethur emulator button home --worktree active --json
nethur emulator rotate landscape_left --worktree active --json
nethur emulator exec --command "tap 0.5 0.7" --worktree active --json
nethur emulator kill --worktree active --json
nethur emulator shutdown --worktree active --json

Coordinates are normalized from 0 to 1. Prefer tap for single taps, and use gesture for drags or multi-step touch input. Pass --device <udid-or-name> or --emulator <id> when a script must target a specific simulator instead of the worktree's active emulator.

Linear

The nethur linear surface is what agents use via the nethur-linear skill (legacy install name linear-tickets still works). Prefer --json. Linked worktrees resolve with --current.

Read

bash
nethur linear issue --current --full --json
nethur linear issue ENG-123 --comments --children --relations --activity --json
nethur linear search "auth bug" --workspace all --json
nethur linear list --filter assigned --limit 10 --json
nethur linear list-issues --team ENG --state started --assignee me --json
nethur linear list-issues --query auth --updated-at -P7D --cursor <cursor> --workspace <id> --json
nethur linear team list --json
nethur linear team states --team ENG --json
nethur linear team labels --team ENG --json
nethur linear project list --query launch --json

--full expands comments, children, attachments, relations, and activity. Section flags (--comments, --children, --attachments, --relations, --activity) work individually.

MCP-style write

bash
# Create or update (omit id/--current to create; requires --team and --title on create)
nethur linear save-issue --team ENG --title "Fix auth" --priority high --json
nethur linear save-issue ENG-123 --state "In Progress" --assignee me --json
nethur linear save-issue --current --project null --due-date null --json

nethur linear relation add ENG-1 --related ENG-2 --type blocks --json
nethur linear relation remove ENG-1 --related ENG-2 --type related --json

save-issue labels replace the full label set (Linear MCP save_issue semantics). Literal null clears assignee, estimate, due date, project, or parent.

Field helpers (still valid)

bash
nethur linear status set --current --to "In Progress" --json
nethur linear assignee set --current --me --json
nethur linear priority set ENG-123 --to high --json
nethur linear estimate set --current --to 3 --json
nethur linear due-date set --current --to 2026-08-01 --json
nethur linear label add --current --label backend --json
nethur linear comment add --current --body "Investigating regression" --json
nethur linear attach --current --url https://example.com/repro --title "Repro" --json
nethur linear create --title "Flaky login test" --team ENG --priority high --json

Run nethur linear --help or nethur skills get nethur-linear for the version-matched list. Pass an explicit issue id (e.g. ENG-123) when a script may run outside an Nethür-linked worktree.

Skills (local, no runtime required)

List bundled guides, print a version-matched guide, or install/update hybrid skill packages without the desktop Settings UI:

bash
nethur skills list
nethur skills get nethur-cli
nethur skills get orchestration --references
nethur skills get orchestration --reference recovery-and-cleanup
nethur skills get orchestration --full
nethur skills install --skill nethur-cli --skill orchestration
nethur skills install --all --dry-run
nethur skills update --all

install / update shell out to the same npx skills commands Settings uses. They do not contact the Nethür runtime. See Nethür skills.

Account (host-local runtime)

On a headless host running Nethür (nethur serve or the desktop app), add managed Claude/Codex accounts when the remote client cannot use Add account (remote runtime scope disables that button):

bash
nethur account list
nethur account add                 # Claude by default
nethur account add --agent codex

account add runs claude login / codex login in this terminal on the host, then registers the captured credentials with the local runtime. Codex uses device authorization so the browser can finish on another machine. Run these on the machine that owns the accounts — not through a client-only remote session.

Artifacts

Publish HTML or Markdown through the signed-in Nethür account. Viewing a public link does not require sign-in; create/list/update/delete do. Publishing is off by default — a human must enable Settings → Artifacts → Allow publishing public artifact links on the device. There is no CLI flag that grants the gate. list, unshare, and delete stay available so you can audit or revoke links after turning publishing off.

bash
nethur artifacts share ./report.html --json
nethur artifacts share ./notes.md --json
nethur artifacts update ./notes.md --json
nethur artifacts unshare ./notes.md --json
nethur artifacts list --json
nethur artifacts list --cursor <cursor> --json
nethur artifacts delete <id> --json
  • Accepted files: .html, .htm, .md, .markdown.
  • share stores the edit token in the active Nethür profile and does not print it. update / unshare resolve by the same local path and profile that originally shared the file.
  • list is paged (nextCursor → --cursor). delete takes the artifact id from list and does not need the original file.
  • Relative HTML assets are not uploaded — share self-contained HTML or absolute asset URLs.
  • Denied publish/update fails with artifact_sharing_disabled; fix Settings instead of retrying.
  • Desktop: open a local HTML or Markdown file and use Share as artifact, or manage links from the sidebar Artifacts page.

Automations, environments, and hooks

Scheduled prompts:

bash
nethur automations list --json
nethur automations create --name "Daily review" --trigger daily --time 09:00 --prompt "Review open changes" --provider codex --repo id:<repoId> --disabled --json
nethur automations run <automationId> --json

Remote runtime environments:

bash
nethur environment add --name work-laptop --pairing-code "nethur://pair?code=..." --json
nethur environment list --json
nethur environment rm --environment <selector> --json

Agent status hooks:

bash
nethur agent hooks status --json
nethur agent hooks on --json
nethur agent hooks off --json

Agent habits

  • Prefer --json for automation and agent calls.
  • Prefer selectors over parsing UI labels.
  • Read terminal state before sending input unless the next input is obvious.
  • Use worktree comments for progress checkpoints. See Worktree checkpoints.
  • Use Orchestration for tracked multi-agent dispatches instead of ad hoc terminal prompts.