> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.simplified.com/cli/troubleshooting/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.simplified.com/_mcp/server.

# Troubleshooting

Start by checking the installed version and the command's supported flags:

```bash
simplified --version
simplified posts:create --help
```

These guides describe version 1.8.0. To install the latest published release, use
`npm install -g simplified-cli@latest`.

## The shell cannot find simplified

Confirm Node.js 22 or newer and npm are installed. Run `npm install -g simplified-cli`
in the environment where you intend to use it, then open a new terminal.
Check that your npm global executable directory is on `PATH`. Installing on your
laptop does not install the command in a remote runner or hosted assistant.

## No API key is configured, or access is denied

```bash
simplified auth:list
simplified auth:whoami
simplified teamspace:current
```

If needed, run `simplified auth:login my-workspace` and enter a valid key.
An active saved profile overrides `SIMPLIFIED_API_KEY`. A `401` can indicate an
invalid or revoked credential; a `403` can indicate insufficient access to the
selected workspace or teamspace. Verify the scope before replacing credentials.

If you just changed workspace profiles, select `teamspace:use default`, inspect
`auth:whoami`, then select an accessible teamspace.

## Accounts or content are missing

Confirm the workspace and teamspace first. Use `accounts:list` without a network
filter, then inspect account names and IDs. Social accounts must already be
connected in Simplified. Content lists can be filtered or paginated; inspect
those options before concluding an item is missing.

## A flag or JSON payload is rejected

Use `simplified COMMAND --help` to confirm the flag. Check these common mistakes:

* `posts:create --date` takes a combined date and time; `posts:update` uses separate `--date` and `--time` flags.
* `posts:list` uses `--tz`; scheduled-post updates use `--timezone`.
* Analytics use singular `--account`; post commands use `--accounts`.
* `--json` usually names a file, while options such as `--additional` and `--parameters` take an inline JSON string.
* UUIDs, numeric IDs, local file paths, and remote URLs are not interchangeable.

The multiline shell examples use Bash/zsh-style quoting. Adapt quoting and line
continuations when using another shell. JSON files avoid much of that escaping.

## jq cannot parse the output

Some commands print headings before their JSON data. Do not pipe every command
directly into `jq`. Use the [output-handling guide](/cli/use-from-an-ai-agent#read-command-output)
and inspect the actual result shape. Errors and progress belong on stderr; do
not merge them into stdout when parsing data.

## A media URL cannot be fetched

Check that the URL is reachable without an authenticated browser session and has
not expired. Upload local files with `assets:upload`. For signed asset URLs, use
`assets:get` to retrieve a fresh `file_url`. Wait for processing to complete before
sending an asset into another operation.

## Generation fails or waiting times out

Save the task or variation IDs and query the matching status command. Check the
returned error, selected model's required fields, available credits, and source
assets. A local timeout does not prove a remote job failed. Poll the existing job
before resubmitting to avoid duplicate work.

For AI video, preserve both the art `id` and `art_variation_id`; status needs both.
Generic `image:task` is not the status command for AI image variations.

## A post is not published yet

Check whether it was created as a draft, queued, or scheduled. `add_to_queue`
uses the account's publishing queue, not an explicit immediate-publication flag.
Inspect the post and account connection in Simplified for timing or
platform-specific validation issues.

## Get help with a reproducible report

Include the CLI version, command name, non-secret flags, error text, and relevant
job identifiers. Remove API keys and private content before sharing logs. The
[command reference](/cli/command-reference) links each command family to its guide.

> Resolve installation, authentication, input, and asynchronous-job issues.