Troubleshooting

"command not found: plext"

Install path issue. After brew install plext-cli or npm install -g plext-cli, verify:

which plext
plext --version

If which returns nothing, your shell isn't seeing the install path. Check $PATH contains the install directory (/opt/homebrew/bin or wherever your global npm bin lives).

401 from every command

Token expired or revoked. Re-authenticate:

plext logout
plext login

If you're using an API key (PLEXT_API_KEY or --api-key), the key may have been revoked from the dashboard. Mint a new one.

`key_workspace_mismatch`

Your API key was minted in a different workspace than the project is currently linked to.

Two fixes:

Re-link the project to the workspace the key is scoped to:
```
plext link --workspace <slug> --api-key plxt_…
```
Or use a key minted in the correct workspace.

The error surfaces up front (before the actual API call) so you don't get confusing 403s on every operation.

`plex_not_writable` / `plex_not_deletable`

The plex was linked at a lower access level than the operation requires. Re-run plext link with --access to upgrade:

# Upgrade the "decisions" plex to full access
plext link --access decisions=full

The three levels:

Level	Allows
`read`	Read only
`write`	Read + write (no delete)
`full`	Read + write + delete

Wrong workspace

Inspect:

plext status

Re-link to a different workspace:

plext link --workspace my-other-team

"plext stopped" errors from agent skills

The skill is installed but the project is stopped. Start it:

plext start

Local-only commands (plex list, plex show, plex search) work when stopped. Data commands (note create, etc.) require start.

Filing a bug

Include in your report:

CLI version: plext --version
Project status: plext status
Error output (full stack/JSON if available)
X-Request-ID from the failed API call (if you have it)
What you were trying to do

Report at the GitHub issue tracker for plext-cli.