Suggestions

promptless suggestions lists the docs updates the Promptless platform has drafted for your organization — the same queue you see on the “suggestions pending review” page in the dashboard. Use it to triage open work, narrow in on a single page or trigger source, or pipe machine-readable output into another tool.

Usage

promptless suggestions [options]

By default the command prints the 10 most recent pr_open suggestions for your organization, newest first. (An API key is scoped to a single org — see Authentication below.)

$ promptless suggestions

  ID         STATUS     REMOTE              PR      PAGE                                          TRIGGER                CREATED
  sg_a1b2c   pr_open    Promptless/docs     #3402   src/content/docs/docs/getting-started.mdx     slack C0B2WNQ3CM9      38m ago
  sg_d3e4f   pr_open    Promptless/docs     #3398   src/content/docs/docs/integrations/linear…    PR promptless#3398     5h ago
  sg_g5h6i   pr_open    Promptless/runtime  #3401   runtime/dispatch/prompts/notification_skill…  slack C0B2WNQ3CM9      5h ago
  ...

  Showing 10 of 23. Use --limit, --all, or filters to narrow.

The footer always reports how many suggestions matched in total, so the implicit limit is never silent.

Columns:

Column	Source
`ID`	The suggestion’s UUID, abbreviated. Pass the full or short ID to `--id` for detail.
`STATUS`	One of `ready`, `pr_open`, `published`, `closed`. Same statuses the dashboard uses.
`REMOTE`	The docs repo the suggestion targets, derived from `collection_name` + `docs_platform`. Blank if the suggestion’s collection is not a git remote (e.g. ReadMe, Zendesk).
`PR`	The pull request number once the suggestion has opened one. Blank in `ready`.
`PAGE`	The first impacted file. Use `--stat` to see all of them with change types.
`TRIGGER`	A short label for what produced the suggestion: `slack <channel>`, `PR <repo>#<n>`, `web`, `api`. Pulled from the first trigger event.
`CREATED`	Relative time. Use `--json` for ISO timestamps.

Filters

The Promptless API returns every suggestion in the org and the CLI filters locally — the same way the dashboard does. Filters compose with AND; pass several to narrow further.

Flag	Description
`--status <status>`	One of `ready`, `pr_open`, `published`, `closed`. Repeat the flag to include several (`--status ready --status pr_open`). Defaults to `pr_open`. Pass `--status any` to include every status.
`--location <name>`	Restrict by docs location. Matches `collection_name` (e.g. `docs-site`) or `docs_platform:collection_name` for disambiguation.
`--trigger <kind>`	Restrict by trigger source. Accepts `slack`, `web`, `api`, `github`, or a qualified form like `github:Promptless/docs` or `slack:C0B2WNQ3CM9`.
`--label <label>`	Restrict to suggestions carrying a label. Repeat for multiple labels (AND).
`--assignee <user>`	Restrict to suggestions assigned to a specific user.
`--page <path>`	Restrict to suggestions whose impacted files include this path. Glob patterns are honored (`--page 'src/content/docs/**'`).
`-q, --query <expr>`	Pass a raw query expression in the same syntax as the dashboard’s filter box (e.g. `is:pr_open author:alice`). Composed with the structured flags above.
`--since <date>`	Only suggestions created on or after this date. Accepts ISO 8601 (`2026-04-01`) or relative offsets (`7d`, `2w`, `3mo`).
`--until <date>`	Only suggestions created on or before this date.

$ promptless suggestions --status pr_open --status ready --trigger slack --since 7d

  ID         STATUS    REMOTE             PR      PAGE                                         TRIGGER             CREATED
  sg_a1b2c   pr_open   Promptless/docs    #3402   src/content/docs/docs/getting-started.mdx    slack C0B2WNQ3CM9   38m ago
  sg_g5h6i   ready     Promptless/docs    —       src/content/docs/docs/intro.mdx              slack C0B2WNQ3CM9   3h ago

  Showing 2 of 2.

Limit and pagination

The default limit of 10 is a soft cap meant to keep an invocation glanceable.

Flag	Description
`-n, --limit <n>`	Show up to `n` suggestions instead of 10.
`--all`	Disable the limit and print every match.
`--offset <n>`	Skip the first `n` matches. Pairs with `--limit` to page through.

$ promptless suggestions --limit 25
$ promptless suggestions --all --status any
$ promptless suggestions --limit 10 --offset 20    # third page of 10

When the result set exceeds the active limit, the footer says so:

  Showing 10 of 23. Use --limit, --all, or filters to narrow.

The underlying API returns every suggestion in the org in a single response, so --limit and --offset truncate the rendered output rather than reducing what the CLI fetches.

—stat

--stat extends the list view with the git diff --stat-style breakdown of every impacted file:

$ promptless suggestions --stat --limit 3

  sg_a1b2c  pr_open   Promptless/docs  #3402   Update copy: human ownership of authorship
    src/content/docs/docs/getting-started.mdx                                            MOD   +12 -4
    src/content/docs/docs/intro.mdx                                                      MOD    +3 -1
    3 files changed, 18 insertions(+), 6 deletions(-)

  sg_d3e4f  pr_open   Promptless/docs  #3398   Document Linear recording state
    src/content/docs/docs/integrations/linear-integration.mdx                            MOD    +24 -2
    1 file changed, 24 insertions(+), 2 deletions(-)

  sg_g5h6i  pr_open   Promptless/runtime #3401  Add guardrail requiring labeled links
    runtime/dispatch/prompts/notification_skill.md.jinja                                 MOD    +8 -0
    1 file changed, 8 insertions(+), 0 deletions(-)

Per-file line counts are not in the list response, so --stat fetches each shown suggestion’s diff in turn. Expect roughly one extra request per row. Combine with --limit to keep it bounded; combining --stat with --all against a large org is slow and noisy.

The change-type tag (MOD, ADD, DEL) mirrors the dashboard’s MOD / added / deleted badges.

Showing one suggestion in full

The list view is intentionally compact. To read the full body of a single suggestion, look it up by ID:

$ promptless suggestions --id sg_a1b2c

  sg_a1b2c — Update copy: human ownership of authorship
  Status:    pr_open
  Remote:    Promptless/docs
  PR:        https://github.com/Promptless/docs/pull/3402
  Last SHA:  c0ffee1a2b3c
  Trigger:   slack C0B2WNQ3CM9 — "<@U080S8KGDUP> All …" (and 1 other event)
  Created:   2026-05-22T08:36:00Z (38 minutes ago)
  Updated:   2026-05-22T08:54:00Z (20 minutes ago)
  Labels:    copy-edit, onboarding
  Assignees: alice@example.com

  Tighten the install section so it doesn't claim the docs team co-authors
  the page with the LLM. Switch to first-person plural where it's the team
  speaking, and drop the "we partnered with our AI assistant" line.

  Files:
    src/content/docs/docs/getting-started.mdx   MOD   +12 -4
    src/content/docs/docs/intro.mdx             MOD    +3 -1

  3 files changed, 18 insertions(+), 6 deletions(-)

--id ignores filter flags — it’s a direct lookup. Pair with --stat is implied (detail view always shows the file list). If the ID does not exist or you do not have access to it, the command exits non-zero.

JSON output

Pass --json to emit the matched suggestions as a single JSON array suitable for piping into jq or another tool. Field names mirror the API response (id, title, status, pr_status, closed_at, impacted_files[], trigger_events[], collection_name, docs_platform, labels, assignees, last_sha, created_at, updated_at). The implicit limit of 10 still applies in JSON mode unless you set --limit or --all.

$ promptless suggestions --json --status pr_open --limit 3 | jq '.[] | {id, title, pr: .trigger_events[0].metadata.source_pr_number}'

--json --stat additionally embeds the per-file diff stats under each impacted_files[] entry as additions and deletions.

Exit codes

Code	Meaning
0	At least one suggestion matched, or `--id` resolved.
1	No suggestions matched the filters, or `--id` was not found.
2	Argument error (unknown flag, malformed date, conflicting options).

The 1 on “no matches” is intentional so that shell pipelines like promptless suggestions --status ready && echo "nothing to triage" work as expected.

Authentication

suggestions is an authenticated command. It hits api.gopromptless.ai with the bearer key cached by promptless login, resolved through the precedence rules in Configuration.

A Promptless API key is implicitly scoped to a single organization — the one whose dashboard generated it. The server derives the org from the bearer token, so suggestions does not take an --org flag and there is no way to query across organizations from one CLI session. To work against a different org, log out and back in (or point $PROMPTLESS_CLI_API_SECRET at a different key for a single command — see Configuration). promptless whoami always shows which org the current key resolves to.

If the cached key is missing or rejected the command exits non-zero with a pointer back to promptless login — it does not silently fall through to anonymous access.