Configuration

The Plot CLI works without a project config file. Most users only need to run plot login, then plot workspace use <slug> if they have more than one workspace.

Environment Variables

PLOT_CREDENTIAL_STORE

Controls where credentials are stored.

export PLOT_CREDENTIAL_STORE=keyring

XDG_CONFIG_HOME

Overrides the base config directory. When this is set, Plot stores local CLI files under $XDG_CONFIG_HOME/plot. Otherwise it uses ~/.plot.

export XDG_CONFIG_HOME="$HOME/.config"

PLOT_CLI_SKIP_UPDATE_CHECK

Disables the background update check that normally runs at most once per day. This is useful in CI or tight automation loops where each command should do only the requested work.

export PLOT_CLI_SKIP_UPDATE_CHECK=1

PLOT_INSTALL_DIR

Controls where the install script places the plot binary.

PLOT_INSTALL_DIR=~/.local/bin curl -fsSL https://plot.app/cli/install | bash

PLOT_CLI_VERSION

Pins the version used by the install script.

PLOT_CLI_VERSION=0.0.10 curl -fsSL https://plot.app/cli/install | bash

NO_COLOR and FORCE_COLOR

The CLI follows the common NO_COLOR and FORCE_COLOR conventions for terminal color output.

NO_COLOR=1 plot task me
FORCE_COLOR=1 plot task me

Local Files

User-local CLI files are stored in:

~/.plot

If XDG_CONFIG_HOME is set, they are stored in:

$XDG_CONFIG_HOME/plot

Credentials are written with restricted file permissions when file-backed storage is used.

Output Format

Most read commands support:

JSON is the default for most read commands.

plot task get ENG-042 --format json
plot task get ENG-042 --format markdown

List commands return a consistent envelope:

{
  "tasks": [],
  "count": 0,
  "startAt": 0,
  "limit": 20,
  "hasMore": false,
  "nextStartAt": null
}

Use --limit and --start-at to page through longer lists.

Quiet Mode

Spinners and progress messages only render when output is attached to an interactive terminal. When the CLI is piped, redirected, or run by a script or agent, that chrome is suppressed automatically — stdout and stderr stay clean without any extra flag:

plot search "launch notes" --format json

Pass --quiet or -q to force-suppress spinners and progress messages while running in a terminal.

Updates

The CLI checks for new releases in the background at most once per day. The check is best-effort and does not block the command you asked to run.

To update immediately:

plot update

After a successful update, Plot can also refresh the bundled agent skill when skill auto-update is enabled through plot setup.

Analytics

The CLI can send product analytics and reliability signals to help improve the tool. You can check or change the local setting:

plot config get analytics
plot config set analytics false
plot config set analytics true

Errors

Errors are structured and include a code, message, and sometimes a hint:

{
  "error": true,
  "code": "AUTH_REQUIRED",
  "message": "No active workspace. Run `plot login` to authenticate.",
  "hint": "Run 'plot login' to authenticate."
}

Exit codes are grouped by failure type:

If a command returns a hint, follow the hint first.