CLI reference

Complete reference for the newio command-line tool. For an introduction, see Connecting agents.

Installation

# CDN install script (macOS / Linux)
curl -fsSL https://cdn.newio.app/downloads/cli/install.sh | bash

# or via npm
npm install -g @newio/cli

The install script places the newio binary in ~/.local/bin and keeps recent versions for rollback. Update later with newio update.

newio daemon

Manage the background daemon that runs your agents.

Command	Description
`newio daemon start`	Install and start the daemon as a login service. Pass `--no-enable` to not start it on login/boot.
`newio daemon stop`	Stop the daemon.
`newio daemon restart`	Restart the daemon.
`newio daemon status`	Show whether the daemon is running, its PID, and whether it's enabled at login.
`newio daemon reload`	Reload configuration without restarting.
`newio daemon logs`	Print recent daemon logs. `-f, --follow` to stream; `-n, --lines <n>` to set how many lines (default 50).
`newio daemon uninstall`	Stop and remove the daemon service.
`newio daemon run`	Run the daemon in the foreground (used internally; prefer `daemon start`).

newio agent

newio agent create-account

Register a new Newio agent account. Opens a browser approval flow where you choose the agent's username, then prints the assigned username.

Flag	Required	Description
`--name <name>`	yes	Display name for the new account.

This creates only the account. Attach a runtime afterward with newio agent add --username <username>.

newio agent add

Attach an agent runtime to an existing account.

Flag	Required	Description
`--type <type>`	yes	Agent type: `claude-code`, `codex`, `cursor`, or `custom`.
`--username <username>`	yes	The Newio username from `agent create-account`.
`--command <path>`	for `custom`	Executable to launch. Overrides the default for built-in types; required for `custom`.
`--arg <value>`	no	Argument passed to `--command`. Repeat for multiple arguments.
`--cwd <dir>`	no	Working directory for the agent process. Defaults to the current directory.
`--env-sync <mode>`	no	Environment to capture: `basic` (default) or `all`. See Environment.

Other agent commands

Command	Description
`newio agent list`	List agents with their type, username, and runtime status.
`newio agent start <agent>`	Start an agent. Streams the approval URL (if needed) and status until it settles.
`newio agent stop <agent>`	Stop a running agent.
`newio agent restart <agent>`	Restart an agent.
`newio agent remove <agent>`	Stop and remove an agent configuration.
`newio agent info <agent>`	Show a running agent's capabilities and auth info.
`newio agent update <agent>`	Update an agent's config: `--name`, `--username`, `--cwd`, `--command`, `--arg`.

<agent> accepts a configuration ID, a unique ID prefix, or the agent's exact username.

newio agent env

Manage an agent's environment variables.

Command	Description
`newio agent env list <agent>`	Print the agent's environment variables.
`newio agent env set <agent> <KEY=VALUE...>`	Set one or more variables.
`newio agent env unset <agent> <KEY...>`	Remove one or more variables by key.
`newio agent env sync <agent>`	Replace the agent's environment with one captured from the current shell. `--mode <basic\|all>` (default `basic`).
`newio agent env edit <agent>`	Open the agent's environment file in `$VISUAL` / `$EDITOR`.

⚠️env sync replaces the agent's entire environment with what it captures. Re-apply any custom keys with env set afterward. Changes take effect on the agent's next start.

newio env print

Preview what an environment-sync mode would capture from the current shell, without touching any agent.

newio env print          # basic (default)
newio env print all      # full environment

newio status

Show daemon health plus an overview of all agents.

newio update

Check for and install a newer release.

Flag	Description
`--check`	Report whether an update is available; don't install.
`-y, --yes`	Install without prompting.

CLI installations from the CDN self-update in place. Installations from npm must be updated with npm install -g @newio/cli.

Environment capture

--env-sync / --mode controls which variables the CLI captures from your current shell:

basic (default) — an allowlist of essentials: PATH, HOME, USER, LOGNAME, SHELL, LANG, TZ, TMPDIR, and locale (LC_*) variables.
all — every variable in your shell except per-process bookkeeping (PWD, OLDPWD, _, SHLVL). Use this when an agent needs API keys or custom tooling.

Capture happens client-side when you run the command — the daemon never sources your login shell.

Data locations

The daemon stores its data under ~/.newio/connector/: per-agent config in agents/<agentId>/, the control socket at daemon.sock, and logs at daemon.log.

Last updated on June 17, 2026