diff --git a/docs/commands.md b/docs/commands.md new file mode 100644 index 0000000..7f9ba67 --- /dev/null +++ b/docs/commands.md @@ -0,0 +1,58 @@ +# Command reference + +Every command accepts `-h` / `--help` and prints its own usage. + +## Authentication + +| Command | Description | +|---|---| +| `promptless login` | Open a browser, complete the Clerk flow, and cache an API key | +| `promptless logout` | Remove the cached API key (and the file, if it ends up empty) | +| `promptless whoami` | Print the user and organizations associated with the current key | + +Config-file location and env-var precedence are documented in [Configuration](configuration.md). The protocol between the CLI and the Promptless web app is documented in [CLI auth protocol](cli-auth-protocol.md). + +## Suggestions + +| Command | Description | +|---|---| +| `promptless suggestions [filters]` | List docs suggestions (default: 10 most recent, status=pr_open) | +| `promptless suggestions --stat [filters]` | Same list with a `git diff --stat`-style per-file breakdown | +| `promptless suggestions --id ` | Show a single suggestion in full, including the file list and stats | +| `promptless suggestions --json [filters]` | Emit JSON for scripting | + +Filter flags: `--status` (repeatable; one of `ready`, `pr_open`, `published`, `closed`, or `any`), `--location`, `--trigger`, `--label`, `--assignee`, `--page`, `--since`, `--until`, `-q/--query` (dashboard-syntax filter expression). Limit flags: `-n/--limit`, `--all`, `--offset`. See [Suggestions](suggestions.md) for details. + +## Local linting + +| Command | Description | +|---|---| +| `promptless slop-cop ...` | Detect LLM prose tells in text files; runs entirely locally | +| `promptless slop-cop --debug ...` | Verbose debug output for rule authors | +| `promptless slop-cop --format ...` | Force the input parser (`auto`, `text`, `markdown`, `mdx`, `pandoc`) | + +Exit codes: `0` clean, `1` violations found, `2` argument error. `slop-cop` is the only command that does no network I/O. + +## Web tools + +| Command | Description | +|---|---| +| `promptless agentview ` | Fetch a page and print the markdown a coding agent will read | +| `promptless agentview -o ` | Write the extracted markdown to a file instead of stdout | + +## Shell integration + +| Command | Description | +|---|---| +| `promptless completion zsh` | Print a zsh completion script | +| `promptless completion bash` | Print a bash completion script | +| `promptless completion fish` | Print a fish completion script | + +Pipe the output into the appropriate location for your shell — e.g. `promptless completion zsh > ~/.zsh/completion/_promptless`. + +## Global conventions + +- Every command also responds to the short alias `pless`. +- Authenticated commands resolve the API key in this order: `$PROMPTLESS_CLI_API_SECRET`, then the cached config file. See [Configuration](configuration.md). +- Authenticated commands exit non-zero with a pointer back to `promptless login` if the key is missing or rejected — they never fall through to anonymous access. +- JSON output, where supported, is a single JSON value on stdout. Diagnostics go to stderr so `| jq` is safe. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..4dbbd88 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,82 @@ +# promptless + +A command-line companion for tech writers. The CLI surfaces docs work the Promptless platform has done on your behalf — detected prose tells, pending suggestions, agent-readable views of your published pages — without forcing you out of the terminal. + +## How it works + +Promptless runs as a hosted service that watches your docs and produces suggestions, audits, and analyses. The CLI is the local-side handle on that service. It authenticates once, then offers focused commands that each map to a single thing you would otherwise click through the web app to do. + +This means you can: + +- Triage open suggestions from your editor or terminal +- Lint your own drafts for LLM prose tells before committing +- See exactly what markdown a coding agent will read when it crawls a published page +- Drop authenticated calls into scripts and CI without juggling browser cookies + +## Getting started + +``` +npm install -g github:Promptless/promptless-cli +promptless login +promptless whoami +``` + +`login` pops a browser, completes the Clerk handshake, and writes a long-lived API key to a config file under `~/.config/promptless/`. Every other command reads that file. See [Configuration](configuration.md) for path resolution and [Environment variables](environment-variables.md) for the overrides used by tests and staging. + +## Commands + +`promptless login`, `promptless logout`, `promptless whoami`, `promptless suggestions`, `promptless slop-cop`, `promptless agentview`, and `promptless completion`. See the full [command reference](commands.md). + +The short alias `pless` is installed alongside `promptless` and accepts the same arguments. + +## A day with promptless + +Suppose you maintain the docs for a small developer tool. Here's what a typical morning might look like. + +### Check what's waiting for you + +``` +$ 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. +``` + +Ten open suggestions, newest first. The default is intentionally short — see [Suggestions](suggestions.md) for filtering by docs location, trigger, status, label, or free-text query, and the `--stat` flag for a `git diff --stat`-style per-file breakdown. + +### Read one in full + +``` +$ promptless suggestions --id sg_a1b2c +``` + +The list view is compact on purpose. `--id` shows the full body and suggested diff for a single suggestion. + +### Draft a fix and lint it before you push + +``` +$ promptless slop-cop docs/intro.md +``` + +`slop-cop` flags the rhetorical and structural tells of LLM-generated prose so you can fix them before they ship. It is the only command that does no network I/O — pure local linting. + +### See the page the way an agent will + +``` +$ promptless agentview https://docs.example.com/intro +``` + +Coding agents do not see your CSS or chrome — they see the markdown extracted from `
`. `agentview` prints exactly that, so you can audit what an agent will actually quote back. + +## Configuration + +The CLI stores a single piece of state: the cached API key. Path resolution, env-var overrides, and file permissions are documented in [Configuration](configuration.md). + +Server endpoints (`app.gopromptless.ai` and `api.gopromptless.ai` by default) can be pointed at staging or a local stack via the variables in [Environment variables](environment-variables.md). + +The login flow and the contract between the CLI and the Promptless web app is documented separately in [CLI auth protocol](cli-auth-protocol.md), which is primarily of interest if you are working on the CLI itself. diff --git a/docs/suggestions.md b/docs/suggestions.md new file mode 100644 index 0000000..15ccdd0 --- /dev/null +++ b/docs/suggestions.md @@ -0,0 +1,171 @@ +# 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](#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 `, `PR #`, `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 ` | 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 ` | Restrict by docs location. Matches `collection_name` (e.g. `docs-site`) or `docs_platform:collection_name` for disambiguation. | +| `--trigger ` | Restrict by trigger source. Accepts `slack`, `web`, `api`, `github`, or a qualified form like `github:Promptless/docs` or `slack:C0B2WNQ3CM9`. | +| `--label