Skip to content
NRNSNRNSNRNS Help

Agent workflows

Because nrn is a thin client around the same gateway the web app uses, it’s a natural fit for coding agents and CI jobs that need to read or update tasks as part of their own run — an agent picking up a task, working it, and reporting back; a CI job commenting a build result; a script filing sub-tasks for a larger piece of work.

Authenticating a long-running job

Section titled “Authenticating a long-running job”

For an agent environment or CI job, set the NRN_TOKEN environment variable to a token from a grant made once via nrn auth login, rather than running an interactive login every time. Since every grant is workspace-scoped, mint one that covers only the workspace(s) the job actually needs — see Authentication for how grants are scoped, and revoke it from Settings → Connected accounts the moment the job no longer needs it, or if the token leaks.

Create, then comment progress

Section titled “Create, then comment progress”

A common pattern is to create the task the agent is about to work, then post comments at real checkpoints instead of going silent until the end:

nrn task create --project <slug> --title "Fix flaky upload test" --assignee me
# → "Created ENG-99"
nrn task comment ENG-99 "Starting: reproduced the flake locally."
nrn task comment ENG-99 "Root cause: a race in the retry timer. Fix in progress."
nrn task update ENG-99 --status Done

--json on task view and task list gives structured output that’s easy to parse back into a script instead of scraping table text.

Sub-tasks with –parent

Section titled “Sub-tasks with –parent”

Break a larger task down by creating sub-tasks under it — they inherit the parent’s project, so --project isn’t needed:

nrn task create --parent ENG-99 --title "Write a regression test"
nrn task create --parent ENG-99 --title "Fix the retry timer race"
nrn task list --parent ENG-99

Linking a PR

Section titled “Linking a PR”

Once a PR opens for the work, link it to the task so the task shows the PR without anyone copying the URL over by hand:

nrn task link ENG-99 --url https://github.com/org/repo/pull/123 --type pr

Call task link again for a second PR or a branch — a task can carry more than one linked resource.

Docs from a task

Section titled “Docs from a task”

For write-ups that deserve more room than a comment — a design note, a postmortem — create a document straight from the task instead of stuffing it into the description:

nrn doc create --task ENG-99 --title "Root cause notes" --content "$(cat notes.md)"

See Task-linked docs for how the resulting document shows up in the Docs app.

Reading exit codes

Section titled “Reading exit codes”

Scripts can branch on the exit code instead of parsing stderr text:

Code Meaning
0 Success.
2 Usage error — a missing or invalid flag. Nothing was sent to the gateway.
3 Not logged in, or the token is invalid.
4 The current grant doesn’t cover this workspace or action.
1 A network failure, rate limit, or any other gateway error.

The safety model

Section titled “The safety model”

Every nrn login is a workspace-scoped grant, not account-wide access — an agent’s credential can only reach the workspace(s) it was explicitly approved for, and only the operations the gateway allowlist exposes (see CLI overview). Scope an agent’s grant to the smallest set of workspaces it needs, and revoke it from Settings → Connected accounts as soon as the job is done or the credential is no longer trusted.

Next steps

Section titled “Next steps”