CLI getting started

The Retask CLI (retask) drives the same API as the web app from your terminal or scripts.

Install

macOS / Linux

curl -fsSL https://retask.work/install.sh | sh

Windows (PowerShell)

irm https://retask.work/install.ps1 | iex

The installer adds retask to your user PATH, but that change only reaches programs started afterwards — this session still has the PATH it was created with. Add it to the current session so you can carry on without reopening anything:

$env:Path += ";$env:LOCALAPPDATA\retask\bin"

A new tab is not always a new environment

If you skip the line above and reopen your terminal instead, close every Windows Terminal window first — new tabs inherit the environment of the window that spawned them, so a fresh tab in an old window still won’t find retask. In VS Code, restart VS Code itself, not just the integrated terminal.

Check the installed version at any time with:

retask -v

To update to the latest release, run retask upgrade, then retask -v again to confirm the new version.

Authenticate

There are two ways to authenticate. Pick whichever fits.

With a Personal Access Token

Set your Personal Access Token, then run retask auth login to exchange it for a token:

macOS / Linux

export NWEB_API_KEY="nweb_pat_..."
retask auth login

Windows (PowerShell)

$env:NWEB_API_KEY = "nweb_pat_..."
retask auth login

These last for the current session. To avoid leaving your PAT in PowerShell’s saved command history, prompt for it instead:

$env:NWEB_API_KEY = Read-Host 'Paste your PAT'

To set one permanently for your user account, use [Environment]::SetEnvironmentVariable('NWEB_API_KEY', 'nweb_pat_...', 'User') — like the PATH change above, it applies to new sessions only.

If NWEB_API_KEY isn’t set, retask auth login prompts for it interactively (input is masked), with a link to create one at app.retask.work/access-tokens.

Picking a workspace

You don’t need to set NWEB_WORKSPACE_ID up front any more. Leave it unset and retask auth login looks up the workspaces your account belongs to and lets you pick one with the arrow keys.

Set NWEB_WORKSPACE_ID yourself only if you want to skip the picker — it’s still required for non-interactive contexts like scripts and CI, where there’s no terminal to prompt on:

macOS / Linux

export NWEB_WORKSPACE_ID="00000000-0000-0000-0000-000000000000"  # workspace UUID

Windows (PowerShell)

$env:NWEB_WORKSPACE_ID = "00000000-0000-0000-0000-000000000000"  # workspace UUID

Belong to more than one workspace? See Multiple workspaces below.

With an existing token

If you already have a token, set NWEB_API_TOKEN and you’re ready to go — the token already identifies your workspace, so you do not need NWEB_API_KEY or NWEB_WORKSPACE_ID, and you can skip retask auth login:

macOS / Linux

export NWEB_API_TOKEN="..."

Windows (PowerShell)

$env:NWEB_API_TOKEN = "..."

Other optional environment variables: NWEB_API_ENDPOINT, RETASK_PROFILE, RETASK_NO_PERSIST.

Multiple workspaces

Each login is saved into a profile — one profile holds one workspace’s endpoint, workspace ID, and cached token. To work with several workspaces, log in once per workspace and give each login a name:

macOS / Linux

export NWEB_API_KEY="nweb_pat_..."
retask auth login --profile acme

export NWEB_API_KEY="nweb_pat_..."
retask auth login --profile beta

Windows (PowerShell)

$env:NWEB_API_KEY = "nweb_pat_..."
retask auth login --profile acme

$env:NWEB_API_KEY = "nweb_pat_..."
retask auth login --profile beta

Each run picks a workspace as usual and stores it under that name. From then on, --profile chooses which one a command talks to — it works on every command:

retask project list --profile acme
retask task list --profile beta

To fix a profile for a whole shell instead of repeating the flag, set RETASK_PROFILE:

macOS / Linux

export RETASK_PROFILE=acme

Windows (PowerShell)

$env:RETASK_PROFILE = "acme"

If you’re ever unsure which workspace a profile points at, ask:

retask auth whoami --profile acme

Logging in with a name doesn't switch your default

retask auth login --profile acme saves credentials under acme — it does not make acme the profile that plain commands use. A command with no --profile and no RETASK_PROFILE uses the profile named by active_profile in ~/.config/retask/config.yaml, which starts out as default and only changes if you edit that file yourself.

So if you log in with --profile and then run a bare retask project list, you’ll be talking to whichever workspace default holds — not the one you just signed into.

First commands

retask project list
retask task create --project-id <id> --title "Fix login bug" --priority HIGH

See the command reference for every command.