outrank-cli 0.1.1 → 0.2.0

package/README.md

@@ -4,20 +4,20 @@ Agent-first CLI for the Outrank agent API.
 
 ## Install
 
-Requires Node.js 18+.
+Requires Node.js 18+. Works on macOS, Linux, and Windows.
 
-```powershell
+```bash
 npm install -g outrank-cli
 outrank-cli --help
 ```
 
 Or run it from a clone without installing globally:
 
-```powershell
+```bash
 git clone https://github.com/Outrank-SAS/outrank-cli.git
 cd outrank-cli
 npm install
-node .\src\index.js --help
+node ./src/index.js --help
 ```
 
 ## Get an API key
@@ -35,10 +35,19 @@ This repo currently targets the agent endpoints that already exist in `outrank`:
 
 - `auth whoami`
 - `products list|get|create|update|pause|resume`
+- `products integrations providers|prepare|connect|poll|validate|list|create|get|update|test|delete`
+- `products integrations notion databases|schema`
+- `products integrations framer collections|fields`
+- `products integrations webflow sites|collections|fields|items`
 - `products output-settings get|update` for product article settings
 - `products target-audiences list|replace`
 - `products competitors list|replace`
 - `products gsc status|connect|poll|reconnect|disconnect|accounts|properties|set-property|performance|search-analytics|inspect-url|cannibalization`
+- `products linking sources get|update`
+- `products linking detect`
+- `products linking target-config get|update`
+- `products linking targets list|add-manual|upsert|clear-customizations|delete`
+- `products backlinks get|update|credits|earned|unverified|check-removal|reverify|subscription|subscribe-quote`
 - `keywords list|get|export|generation-status|add|suggest|generate|reschedule|bulk-reschedule|delete|bulk-delete`
 - `articles list|get|get-content|update|update-content|replace|bulk-replace|upload-image|upload-featured-image|retry-publish|delete|precreate|generate`
 - `subscription status`
@@ -58,29 +67,31 @@ The CLI reads credentials in this order of precedence:
 
 Pick one. For interactive use on your own machine, `auth login` is simplest. For CI / ephemeral environments, prefer the env var.
 
-```powershell
+```bash
 # One-time persistent setup
 outrank-cli auth login outr_live_xxx
 outrank-cli auth status     # confirms the key is stored
 outrank-cli auth whoami     # round-trips it against the server
 
 # OR per-shell env var (no config file written)
-$env:OUTRANK_API_KEY = "outr_live_xxx"
+export OUTRANK_API_KEY="outr_live_xxx"   # macOS / Linux (bash, zsh)
 outrank-cli auth whoami
 
 # OR per-call (useful in scripts)
 outrank-cli auth whoami --api-key outr_live_xxx
 ```
 
+On Windows PowerShell, set the env var with `$env:OUTRANK_API_KEY = "outr_live_xxx"`. On Windows `cmd.exe`, use `set OUTRANK_API_KEY=outr_live_xxx`.
+
 Sign out / rotate:
 
-```powershell
+```bash
 outrank-cli auth logout     # clears apiKey from ~/.outrank/config.json
 ```
 
 ## Examples
 
-```powershell
+```bash
 outrank-cli auth login outr_live_xxx
 outrank-cli auth status
 outrank-cli auth whoami
@@ -92,8 +103,8 @@ outrank-cli articles get 00000000-0000-0000-0000-000000000000
 outrank-cli articles get-content 00000000-0000-0000-0000-000000000000 --format html
 outrank-cli articles update 00000000-0000-0000-0000-000000000000 --json '{"title":"New title"}'
 outrank-cli articles update 00000000-0000-0000-0000-000000000000 --json '{"image_url":"https://example.com/featured.jpg"}'
-outrank-cli articles upload-image --file .\diagram.png --article 00000000-0000-0000-0000-000000000000
-outrank-cli articles upload-featured-image 00000000-0000-0000-0000-000000000000 --file .\hero.jpg
+outrank-cli articles upload-image --file ./diagram.png --article 00000000-0000-0000-0000-000000000000
+outrank-cli articles upload-featured-image 00000000-0000-0000-0000-000000000000 --file ./hero.jpg
 outrank-cli articles replace 00000000-0000-0000-0000-000000000000 --json '{"find":"Old brand","replace_with":"New brand","preview_only":true}'
 outrank-cli articles retry-publish 00000000-0000-0000-0000-000000000000
 outrank-cli articles precreate 00000000-0000-0000-0000-000000000000
@@ -101,17 +112,54 @@ outrank-cli articles generate 00000000-0000-0000-0000-000000000000
 outrank-cli subscription status
 outrank-cli usage stats
 outrank-cli products get 00000000-0000-0000-0000-000000000000
+outrank-cli products integrations providers
+outrank-cli products integrations prepare wordpress-plugin 00000000-0000-0000-0000-000000000000
+outrank-cli products integrations connect wordpress-com 00000000-0000-0000-0000-000000000000 --json '{"name":"Main WordPress.com","publish_status":"publish"}'
+outrank-cli products integrations connect notion 00000000-0000-0000-0000-000000000000
+outrank-cli products integrations poll wordpress-com 00000000-0000-0000-0000-000000000000 --attempt-id <attempt-id>
+outrank-cli products integrations poll notion 00000000-0000-0000-0000-000000000000 --attempt-id <attempt-id>
+outrank-cli products integrations notion databases 00000000-0000-0000-0000-000000000000 11111111-1111-1111-1111-111111111111
+outrank-cli products integrations notion schema 00000000-0000-0000-0000-000000000000 11111111-1111-1111-1111-111111111111 aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
+outrank-cli products integrations framer collections --json '{"project_url":"https://framer.com/projects/your-project","server_api_key":"framer_server_key"}'
+outrank-cli products integrations framer fields --json '{"project_url":"https://framer.com/projects/your-project","server_api_key":"framer_server_key","collection_id":"collection_id"}'
+outrank-cli products integrations webflow sites --json-file webflow-sites.json
+outrank-cli products integrations webflow collections --json '{"api_token":"wf_token","site_id":"site_id"}'
+outrank-cli products integrations webflow fields --json '{"api_token":"wf_token","collection_id":"collection_id"}'
+outrank-cli products integrations webflow items --json '{"api_token":"wf_token","collection_id":"collection_id"}'
+outrank-cli products integrations validate webhook --json '{"endpoint":"https://api.example.com/webhook","access_token":"secret"}'
+outrank-cli products integrations validate framer --json '{"project_url":"https://framer.com/projects/your-project","server_api_key":"framer_server_key"}'
+outrank-cli products integrations validate shopify --json '{"access_token":"shpat_xxx"}'
+outrank-cli products integrations validate webflow --json '{"api_token":"wf_token"}'
+outrank-cli products integrations validate wix --json '{"site_id":"00000000-0000-0000-0000-000000000000","api_key":"wix_api_key"}'
+outrank-cli products integrations validate wordpress-plugin --json '{"domain":"https://example.com","api_key":"secret-token"}'
+outrank-cli products integrations validate ghost --json '{"url":"https://example.ghost.io","api_key":"abcdef1234567890:abcdef1234567890abcdef1234567890"}'
+outrank-cli products integrations list 00000000-0000-0000-0000-000000000000
+outrank-cli products integrations create 00000000-0000-0000-0000-000000000000 --json '{"provider":"webhook","name":"Main Webhook","endpoint":"https://api.example.com/webhook","access_token":"secret"}'
+outrank-cli products integrations create 00000000-0000-0000-0000-000000000000 --json '{"provider":"framer","name":"Main Framer","project_url":"https://framer.com/projects/your-project","server_api_key":"framer_server_key","author_name":"Outrank AI","publish_mode":"deploy","collection_setup_mode":"create"}'
+outrank-cli products integrations create 00000000-0000-0000-0000-000000000000 --json '{"provider":"shopify","name":"Main Shopify","access_token":"shpat_xxx","blog_id":"123456789","author_name":"Outrank","publish_status":"publish"}'
+outrank-cli products integrations create 00000000-0000-0000-0000-000000000000 --json '{"provider":"wix","name":"Main Wix","site_id":"00000000-0000-0000-0000-000000000000","api_key":"wix_api_key","publish_status":"publish"}'
+outrank-cli products integrations create 00000000-0000-0000-0000-000000000000 --json-file webflow-create.json
+outrank-cli products integrations create 00000000-0000-0000-0000-000000000000 --json '{"provider":"wordpress-plugin","domain":"https://example.com","api_key":"secret-token"}'
+outrank-cli products integrations create 00000000-0000-0000-0000-000000000000 --json '{"provider":"ghost","name":"Main Ghost","url":"https://example.ghost.io","api_key":"abcdef1234567890:abcdef1234567890abcdef1234567890","publish_status":"draft"}'
+outrank-cli products integrations create 00000000-0000-0000-0000-000000000000 --json '{"provider":"nextjs-blog"}'
+outrank-cli products integrations get 00000000-0000-0000-0000-000000000000 11111111-1111-1111-1111-111111111111
+outrank-cli products integrations update 00000000-0000-0000-0000-000000000000 11111111-1111-1111-1111-111111111111 --json '{"endpoint":"https://api.example.com/webhook-v2"}'
+outrank-cli products integrations update 00000000-0000-0000-0000-000000000000 11111111-1111-1111-1111-111111111111 --json '{"publish_status":"draft"}'
+outrank-cli products integrations update 00000000-0000-0000-0000-000000000000 11111111-1111-1111-1111-111111111111 --json-file webflow-update.json
+outrank-cli products integrations update 00000000-0000-0000-0000-000000000000 11111111-1111-1111-1111-111111111111 --json '{"domain":"https://example.com/blog","api_key":"new-secret-token"}'
+outrank-cli products integrations update 00000000-0000-0000-0000-000000000000 11111111-1111-1111-1111-111111111111 --json '{"publish_status":"published"}'
+outrank-cli products integrations test 00000000-0000-0000-0000-000000000000 11111111-1111-1111-1111-111111111111
 outrank-cli keywords suggest --product 00000000-0000-0000-0000-000000000000 --theme "email marketing"
 outrank-cli keywords generate --product 00000000-0000-0000-0000-000000000000 --count 10 --source both
-outrank-cli keywords add --product 00000000-0000-0000-0000-000000000000 --json-file .\keywords.json
+outrank-cli keywords add --product 00000000-0000-0000-0000-000000000000 --json-file ./keywords.json
 outrank-cli keywords export --product 00000000-0000-0000-0000-000000000000
-outrank-cli products create --json-file .\product.json
+outrank-cli products create --json-file ./product.json
 # products create now auto-queues the initial ~30-day keyword plan; poll with keywords generation-status / keywords list
 outrank-cli billing portal-url
 outrank-cli products update 00000000-0000-0000-0000-000000000000 --json '{"daily_article_count":2}'
-outrank-cli products output-settings update 00000000-0000-0000-0000-000000000000 --json-file .\output-settings.json
-outrank-cli products target-audiences replace 00000000-0000-0000-0000-000000000000 --json-file .\target-audiences.json
-outrank-cli products competitors replace 00000000-0000-0000-0000-000000000000 --json-file .\competitors.json
+outrank-cli products output-settings update 00000000-0000-0000-0000-000000000000 --json-file ./output-settings.json
+outrank-cli products target-audiences replace 00000000-0000-0000-0000-000000000000 --json-file ./target-audiences.json
+outrank-cli products competitors replace 00000000-0000-0000-0000-000000000000 --json-file ./competitors.json
 outrank-cli products gsc status 00000000-0000-0000-0000-000000000000
 outrank-cli products gsc connect 00000000-0000-0000-0000-000000000000
 outrank-cli products gsc poll 00000000-0000-0000-0000-000000000000 --attempt-id <attempt-id>
@@ -122,6 +170,24 @@ outrank-cli products gsc performance 00000000-0000-0000-0000-000000000000 --mont
 outrank-cli products gsc search-analytics 00000000-0000-0000-0000-000000000000 --dimensions query,page --limit 50 --query "brand"
 outrank-cli products gsc inspect-url 00000000-0000-0000-0000-000000000000 --url https://example.com/blog/post
 outrank-cli products gsc cannibalization 00000000-0000-0000-0000-000000000000
+outrank-cli products linking sources get 00000000-0000-0000-0000-000000000000
+outrank-cli products linking sources update 00000000-0000-0000-0000-000000000000 --json-file ./linking-sources.json
+outrank-cli products linking detect 00000000-0000-0000-0000-000000000000
+outrank-cli products linking target-config update 00000000-0000-0000-0000-000000000000 --json '{"only_prioritized":true}'
+outrank-cli products linking targets list 00000000-0000-0000-0000-000000000000
+outrank-cli products linking targets add-manual 00000000-0000-0000-0000-000000000000 --json-file ./manual-target.json
+outrank-cli products linking targets upsert 00000000-0000-0000-0000-000000000000 --json-file ./target-upsert.json
+outrank-cli products linking targets clear-customizations 00000000-0000-0000-0000-000000000000 11111111-1111-1111-1111-111111111111
+outrank-cli products linking targets delete 00000000-0000-0000-0000-000000000000 11111111-1111-1111-1111-111111111111
+outrank-cli products backlinks get 00000000-0000-0000-0000-000000000000
+outrank-cli products backlinks update 00000000-0000-0000-0000-000000000000 --json '{"enabled":true,"min_domain_rating":10}'
+outrank-cli products backlinks credits 00000000-0000-0000-0000-000000000000
+outrank-cli products backlinks earned 00000000-0000-0000-0000-000000000000 --limit 10 --include-article
+outrank-cli products backlinks unverified 00000000-0000-0000-0000-000000000000 --limit 10
+outrank-cli products backlinks check-removal 00000000-0000-0000-0000-000000000000 11111111-1111-1111-1111-111111111111
+outrank-cli products backlinks reverify 00000000-0000-0000-0000-000000000000 11111111-1111-1111-1111-111111111111
+outrank-cli products backlinks subscription 00000000-0000-0000-0000-000000000000
+outrank-cli products backlinks subscribe-quote 00000000-0000-0000-0000-000000000000 --plan premium
 outrank-cli keywords reschedule 00000000-0000-0000-0000-000000000000 --scheduled-for 2026-05-20
 outrank-cli billing purchase-products quote --additional-products 2
 ```
@@ -140,6 +206,69 @@ outrank-cli billing purchase-products quote --additional-products 2
 - Analyze overlapping-query cannibalization with `outrank-cli products gsc cannibalization <product-id>`.
 - Use `reconnect` when the token is expired and `disconnect` to remove the product connection.
 
+## Linking workflow
+
+- Inspect current source selection with `outrank-cli products linking sources get <product-id>`.
+- Update the primary or additional sources with `outrank-cli products linking sources update <product-id> --json-file linking-sources.json`.
+- Re-run discovery with `outrank-cli products linking detect <product-id>`.
+- List saved targets with `outrank-cli products linking targets list <product-id>`.
+- Add a manual on-domain URL with `outrank-cli products linking targets add-manual <product-id> --json-file manual-target.json`.
+- Create or update a saved target with `outrank-cli products linking targets upsert <product-id> --json-file target-upsert.json`.
+- Inspect or update product-wide behavior with `outrank-cli products linking target-config get|update <product-id>`.
+- Clear custom anchor text with `outrank-cli products linking targets clear-customizations <product-id> <target-id>`.
+- Remove a stale target with `outrank-cli products linking targets delete <product-id> <target-id>`.
+
+Example payloads:
+
+```json
+{
+  "source_type": "sitemap",
+  "source_url": "https://example.com/sitemap.xml",
+  "additional_linking_sources": [
+    {
+      "id": "docs-root",
+      "source_type": "root_url",
+      "source_url": "https://docs.example.com/blog",
+      "purpose": "linking"
+    }
+  ]
+}
+```
+
+```json
+{
+  "url": "https://example.com/blog/best-page",
+  "title": "Best Page",
+  "is_prioritized": true,
+  "anchor_texts": [
+    "best page",
+    "example guide"
+  ]
+}
+```
+
+## Backlinks workflow
+
+- Inspect current backlink settings with `outrank-cli products backlinks get <product-id>`.
+- Update backlink settings with `outrank-cli products backlinks update <product-id> --json-file backlinks.json`.
+- Inspect current credits with `outrank-cli products backlinks credits <product-id>`.
+- Review earned backlinks with `outrank-cli products backlinks earned <product-id> --limit 20`.
+- Add `--include-article` or `--include-summary` when the human needs article context in the earned list.
+- Review the unverified queue with `outrank-cli products backlinks unverified <product-id> --limit 20`.
+- Trigger a live removal check with `outrank-cli products backlinks check-removal <product-id> <backlink-id>`.
+- Trigger manual reverification with `outrank-cli products backlinks reverify <product-id> <backlink-id>`.
+- Inspect the current backlink subscription state with `outrank-cli products backlinks subscription <product-id>`.
+- Quote a dashboard-equivalent subscription plan with `outrank-cli products backlinks subscribe-quote <product-id> --plan premium`.
+
+Example payload:
+
+```json
+{
+  "enabled": true,
+  "min_domain_rating": 10
+}
+```
+
 ## Keyword mutation rules
 
 - Run `outrank-cli keywords generation-status --product <product-id>` before keyword writes when you are not sure the product is writable.
@@ -157,22 +286,72 @@ outrank-cli billing purchase-products quote --additional-products 2
 - Featured image can be updated either by hosted URL through `articles update --json '{"image_url":"..."}'` or by local-file upload through `articles upload-featured-image`.
 - In-content images can be uploaded from a local file with `articles upload-image`; the command returns the hosted URL plus generated alt text so the agent can insert or replace the markdown image reference.
 - Per-article instructions are stored on the linked scheduled keyword, so `articles update --json '{"instructions":"..."}'` only works for articles that still have a linked planner keyword.
+- `articles update --json '{"status":"published"}'` now attempts a real publish through the product's active integration for eligible attached articles; it is not just a local status flip.
 - Slug is returned for read-only reference but cannot be changed through the agent API.
 - `articles generate <keyword-id>` is only valid for scheduled keywords due today; it mirrors the dashboard's create-and-publish action.
 - `articles precreate <keyword-id>` is only valid for eligible future scheduled keywords, is unavailable on trial subscriptions, and should be polled through the keyword state afterward.
 - `articles update --json '{"status":"published"}'` cannot be used to manually publish a future scheduled article before its due date.
 - `articles retry-publish <article-id>` is only valid for generated articles with a publish error.
 
+## Linking behavior notes
+
+- Linking writes are blocked unless the product has an active backlink subscription.
+- `products linking sources update` accepts `source_type` values `sitemap`, `root_url`, or `integration`.
+- When `source_type` is `sitemap` or `root_url`, `source_url` is required.
+- `additional_linking_sources` is a full replacement list. Each item needs `id`, `source_type`, `source_url`, and `purpose`.
+- `products linking detect` refreshes discovered article URLs from the saved primary source.
+- `products linking targets add-manual` and `upsert` only accept URLs on the product's own domain.
+- `products linking target-config update --json '{"only_prioritized":true}'` requires enough prioritized targets; if not, the API returns a conflict with guidance.
+
+## Backlink behavior notes
+
+- Use `products backlinks update`, not `products update`, for backlink exchange settings.
+- Backlink writes are blocked when the product is hidden for inappropriate content, but reads still work.
+- Setting `min_domain_rating` requires an active backlink subscription.
+- `products backlinks subscribe-quote` is read-only. Purchasing or changing the add-on still requires the dashboard checkout flow.
+- `products backlinks earned` uses cursor pagination through `data.next_cursor`.
+- `products backlinks unverified` is the deduped article-level manual-review stream.
+
+## Integrations workflow
+
+- Inspect connected publishing integrations with `outrank-cli products integrations list <product-id>`.
+- Inspect provider availability with `outrank-cli products integrations providers`.
+- Webhook uses `endpoint` plus `access_token`. Outrank sends `Authorization: Bearer <access_token>` on each request. HMAC signing is not implemented in the current webhook integration.
+- WordPress Plugin uses `domain` plus `api_key`. The Outrank plugin must already be installed and configured on the target site.
+- Start WordPress Plugin setup with `outrank-cli products integrations prepare wordpress-plugin <product-id>`. That mirrors the dashboard flow by generating the integration token first, before validate/create.
+- WordPress.com uses OAuth instead of direct credentials. Start with `outrank-cli products integrations connect wordpress-com <product-id> --json-file wordpress-com-connect.json`, have the human open the returned `connect_url`, then poll with `outrank-cli products integrations poll wordpress-com <product-id> --attempt-id <attempt-id>` until the handoff completes.
+- Notion uses OAuth plus a second configuration step. Start with `outrank-cli products integrations connect notion <product-id>`, have the human open the returned `connect_url`, then poll with `outrank-cli products integrations poll notion <product-id> --attempt-id <attempt-id>`. After OAuth completes, use `outrank-cli products integrations notion databases <product-id> <integration-id>` and `... notion schema <product-id> <integration-id> <database-id>` before `update` to save `name`, `database_id`, and `fields`.
+- Framer uses the newer Server API flow, not the older plugin flow. Start with `outrank-cli products integrations validate framer --json '{"project_url":"https://framer.com/projects/your-project","server_api_key":"framer_server_key"}'`. If you want to publish into an existing user-owned collection, then use `framer collections` and `framer fields` before `create`; otherwise use `collection_setup_mode: "create"` and let Outrank create the collection automatically.
+- Shopify uses a direct app access token. Start with `outrank-cli products integrations validate shopify --json '{"access_token":"shpat_xxx"}'`; the response returns `shop_name` and the available blogs you can use in the create payload, so the human does not need to provide the store name separately.
+- Webflow uses a direct API token plus pre-save discovery. Start with `outrank-cli products integrations validate webflow --json-file webflow-sites.json`, then use `webflow sites`, `webflow collections`, `webflow fields`, and `webflow items` to build the exact create or update payload for the chosen CMS collection.
+- Wix is a direct credential flow using `site_id`, `api_key`, and `publish_status`. Validate first, then create or update directly; there is no OAuth or prepare step.
+- Next.js Blog is a one-step create flow. Run `outrank-cli products integrations create <product-id> --json '{"provider":"nextjs-blog"}'` and store the returned `data.secrets.api_key` immediately because it is not readable later.
+- Validate unsaved webhook, Ghost, Framer, Shopify, Webflow, Wix, or WordPress Plugin credentials with `outrank-cli products integrations validate <provider> --json-file integration.json`.
+- Create a webhook, Ghost, Framer, Shopify, Webflow, Wix, WordPress Plugin, or Next.js Blog integration with `outrank-cli products integrations create <product-id> --json-file integration-create.json`.
+- Inspect one integration with `outrank-cli products integrations get <product-id> <integration-id>`.
+- Update a saved webhook, Ghost, Shopify, Webflow, Wix, WordPress Plugin, or Notion integration with `outrank-cli products integrations update <product-id> <integration-id> --json-file integration-update.json`.
+- Test a saved webhook, Ghost, Framer, Shopify, Webflow, Wix, WordPress Plugin, or Notion integration with `outrank-cli products integrations test <product-id> <integration-id>`.
+- Delete a stale integration with `outrank-cli products integrations delete <product-id> <integration-id>`.
+
+Current scope note:
+
+- Webhook, Ghost, Shopify, Webflow, and Wix support direct validate/create/update/test. Framer supports validate, provider-specific discovery, create, and test for the newer Server API flow. WordPress Plugin supports prepare plus validate/create/update/test. Next.js Blog supports one-step create plus the shared list|get|delete surface, returning a one-time API key on create. WordPress.com supports OAuth connect plus poll, then the shared list|get|delete surface. Notion supports OAuth connect plus poll, provider-specific database/schema discovery, then update/test on the saved row.
+- V2 products are intended to keep one publishing integration. If `list` returns multiple rows, that usually means legacy V1 residue and stale rows should be reviewed and deleted.
+- Backlink exchange management now covers configuration, status reads, earned/unverified review queues, and reverification actions. Purchasing or changing backlink add-ons still requires the dashboard checkout flow.
+- Other providers are still mostly read/delete only while create, update, test, and provider-specific discovery are added one by one.
+
 ## Custom API target (advanced)
 
 The CLI talks to `https://www.outrank.so` by default and you should not need to change that. The override below exists only for Outrank staff debugging against a staging deployment.
 
-```powershell
-$env:OUTRANK_BASE_URL="https://staging.example"
+```bash
+export OUTRANK_BASE_URL="https://staging.example"   # macOS / Linux
 outrank-cli auth whoami
 ```
 
-`--base-url <url>` is the per-command form.
+On Windows PowerShell, use `$env:OUTRANK_BASE_URL = "https://staging.example"`. On Windows `cmd.exe`, use `set OUTRANK_BASE_URL=https://staging.example`.
+
+`--base-url <url>` is the per-command form and works on every platform.
 
 The agent API expects product UUIDs, not numeric ids like `88`.
 
@@ -182,8 +361,8 @@ The agent API expects product UUIDs, not numeric ids like `88`.
 
 If you do not want a global link yet, you can run the CLI directly from this repo:
 
-```powershell
-node .\src\index.js auth whoami --api-key outr_live_xxx
+```bash
+node ./src/index.js auth whoami --api-key outr_live_xxx
 ```
 
 ## JSON-first contract
@@ -198,7 +377,7 @@ This makes the CLI easier for AI agents to drive reliably.
 
 ## Using the agent skill (`SKILL.md`)
 
-`SKILL.md` ships alongside this CLI as a Claude Code skill. It tells an AI agent how to drive `outrank-cli` end-to-end — when to inspect before writing, how to interpret `agent_guidance`, the new-product preflight, the GSC flow, keyword/article rules, and how to handle 401/402/403/409 errors.
+`SKILL.md` ships alongside this CLI as a Claude Code skill. It tells an AI agent how to drive `outrank-cli` end-to-end — when to inspect before writing, how to interpret `agent_guidance`, the new-product preflight, the GSC flow, the linking flow, keyword/article rules, and how to handle 401/402/403/409 errors.
 
 You do not need it if you are using the CLI by hand from a terminal. You want it when you are letting an AI assistant operate the CLI for you.
 

package/SKILL.md

@@ -1,15 +1,16 @@
 ---
 name: outrank
-description: Drive the Outrank agent API from the terminal via outrank-cli. Use when the user asks to list/create/update Outrank products, inspect or manage keyword plans, inspect or edit articles, manage article settings, target audiences, competitors, Google Search Console connections, or quote/buy product slots. Requires outrank-cli on PATH and an Outrank API key (env OUTRANK_API_KEY or stored via auth login).
+description: Drive the Outrank agent API from the terminal via outrank-cli. Use when the user asks to list/create/update Outrank products, inspect or manage publishing integrations, inspect or manage keyword plans, inspect or edit articles, manage article settings, target audiences, competitors, Google Search Console connections, internal linking configuration, or quote/buy product slots. Requires outrank-cli on PATH and an Outrank API key (env OUTRANK_API_KEY or stored via auth login).
 ---
 
 # Outrank Skill
 
 Use `outrank-cli` to drive Outrank from the terminal. The CLI is JSON-first and every command returns `agent_guidance`, so read that field after each step and let it steer the next call.
 
-In human-facing responses, call `products get` / `products update` the product's General settings. These cover the non-editorial product basics such as name, URL, description, sitemap URL, blog root URL, publishing cadence, backlink toggles, and similar core product fields.
-
-In human-facing responses, call product `output-settings` article settings or article preferences. Use `output-settings` only when you are quoting the literal CLI command or API path.
+In human-facing responses, call `products get` / `products update` the product's General settings. These cover the non-editorial product basics such as name, URL, description, sitemap URL, blog root URL, publishing cadence, and similar core product fields.
+
+In human-facing responses, call product `output-settings` article settings or article preferences. Use `output-settings` only when you are quoting the literal CLI command or API path.
+Use `products backlinks ...` for backlink exchange settings, credits, review queues, and reverification actions.
 
 ## Setup
 
@@ -49,9 +50,33 @@ Prefer inspecting before mutating:
 - `outrank-cli keywords export --product <productId>`
 - `outrank-cli products target-audiences list <productId>`
 - `outrank-cli products competitors list <productId>`
+- `outrank-cli products integrations providers`
+- `outrank-cli products integrations list <productId>`
+- `outrank-cli products integrations get <productId> <integrationId>`
+- `outrank-cli products integrations prepare wordpress-plugin <productId>`
+- `outrank-cli products integrations connect wordpress-com <productId> --json-file wordpress-com-connect.json`
+- `outrank-cli products integrations connect notion <productId>`
+- `outrank-cli products integrations poll wordpress-com <productId> --attempt-id <attempt-id>`
+- `outrank-cli products integrations poll notion <productId> --attempt-id <attempt-id>`
+- `outrank-cli products integrations notion databases <productId> <integrationId>`
+- `outrank-cli products integrations notion schema <productId> <integrationId> <databaseId>`
+- `outrank-cli products integrations webflow sites --json-file webflow-sites.json`
+- `outrank-cli products integrations webflow collections --json-file webflow-collections.json`
+- `outrank-cli products integrations webflow fields --json-file webflow-fields.json`
+- `outrank-cli products integrations webflow items --json-file webflow-items.json`
+- `outrank-cli products integrations framer collections --json-file framer-collections.json`
+- `outrank-cli products integrations framer fields --json-file framer-fields.json`
 - `outrank-cli products gsc status <productId>`
 - `outrank-cli products gsc accounts <productId>`
 - `outrank-cli products gsc performance <productId>`
+- `outrank-cli products linking sources get <productId>`
+- `outrank-cli products linking targets list <productId>`
+- `outrank-cli products linking target-config get <productId>`
+- `outrank-cli products backlinks get <productId>`
+- `outrank-cli products backlinks credits <productId>`
+- `outrank-cli products backlinks earned <productId>`
+- `outrank-cli products backlinks unverified <productId>`
+- `outrank-cli products backlinks subscription <productId>`
 - `outrank-cli subscription status`
 - `outrank-cli usage stats`
 
@@ -77,6 +102,23 @@ Write commands currently supported:
 - `outrank-cli products output-settings update <productId> --json-file output-settings.json`
 - `outrank-cli products target-audiences replace <productId> --json-file target-audiences.json`
 - `outrank-cli products competitors replace <productId> --json-file competitors.json`
+- `outrank-cli products integrations validate <provider> --json-file integration.json`
+- `outrank-cli products integrations create <productId> --json-file integration-create.json`
+- `outrank-cli products integrations update <productId> <integrationId> --json-file integration-update.json`
+- `outrank-cli products integrations test <productId> <integrationId>`
+- `outrank-cli products integrations delete <productId> <integrationId>`
+- `outrank-cli products integrations connect wordpress-com <productId> --json-file wordpress-com-connect.json`
+- `outrank-cli products integrations poll wordpress-com <productId> --attempt-id <attempt-id>`
+- `outrank-cli products integrations connect notion <productId>`
+- `outrank-cli products integrations poll notion <productId> --attempt-id <attempt-id>`
+- `outrank-cli products integrations notion databases <productId> <integrationId>`
+- `outrank-cli products integrations notion schema <productId> <integrationId> <databaseId>`
+- `outrank-cli products integrations webflow sites --json-file webflow-sites.json`
+- `outrank-cli products integrations webflow collections --json-file webflow-collections.json`
+- `outrank-cli products integrations webflow fields --json-file webflow-fields.json`
+- `outrank-cli products integrations webflow items --json-file webflow-items.json`
+- `outrank-cli products integrations framer collections --json-file framer-collections.json`
+- `outrank-cli products integrations framer fields --json-file framer-fields.json`
 - `outrank-cli products gsc connect <productId>`
 - `outrank-cli products gsc reconnect <productId>`
 - `outrank-cli products gsc disconnect <productId>`
@@ -84,9 +126,20 @@ Write commands currently supported:
 - `outrank-cli products gsc search-analytics <productId> --dimensions query,page --limit 50`
 - `outrank-cli products gsc inspect-url <productId> --url https://example.com/blog/post`
 - `outrank-cli products gsc cannibalization <productId>`
+- `outrank-cli products linking sources update <productId> --json-file linking-sources.json`
+- `outrank-cli products linking detect <productId>`
+- `outrank-cli products linking target-config update <productId> --json-file target-config.json`
+- `outrank-cli products linking targets add-manual <productId> --json-file manual-target.json`
+- `outrank-cli products linking targets upsert <productId> --json-file target-upsert.json`
+- `outrank-cli products linking targets clear-customizations <productId> <targetId>`
+- `outrank-cli products linking targets delete <productId> <targetId>`
+- `outrank-cli products backlinks update <productId> --json-file backlinks.json`
+- `outrank-cli products backlinks check-removal <productId> <backlinkId>`
+- `outrank-cli products backlinks reverify <productId> <backlinkId>`
+- `outrank-cli products backlinks subscribe-quote <productId> --plan premium|enterprise`
 - `outrank-cli keywords add --product <productId> --json-file keywords.json`
-- `outrank-cli keywords bulk-reschedule --json-file keyword-reschedule.json`
-- `outrank-cli keywords bulk-delete --json-file keyword-delete.json`
+- `outrank-cli keywords bulk-reschedule --json-file keyword-reschedule.json`
+- `outrank-cli keywords bulk-delete --json-file keyword-delete.json`
 - `outrank-cli articles update <articleId> --json-file article-patch.json`
 - `outrank-cli articles update-content <articleId> --json-file article-content.json`
 - `outrank-cli articles replace <articleId> --json-file replace.json`
@@ -158,7 +211,7 @@ If the live API or current repo context does not expose the full allowed option
 - if helpful, show the current value from an existing product as a reference point
 - say clearly when the CLI exposes the field's current value but not the full enum catalog
 
-Business-critical settings that may matter even if the current CLI surface cannot set them yet:
+Business-critical settings that may matter before article generation:
 
 - blog URL or publishing destination
 - internal linking preferences
@@ -166,7 +219,7 @@ Business-critical settings that may matter even if the current CLI surface canno
 - article examples or brand-writing examples
 - publishing workflow preferences such as draft-first vs direct publish
 
-If the human has not provided those business-critical settings yet, say so clearly. Explain which of them are currently exposed by `outrank-cli` and which are not. For settings that are not yet supported by the current CLI surface, do not invent commands. Instead, ask the human whether to:
+If the human has not provided those business-critical settings yet, say so clearly. Explain which of them are currently exposed by `outrank-cli` and which are not. Internal linking is now exposed through the `products linking ...` subtree. For settings that are not yet supported by the current CLI surface, do not invent commands. Instead, ask the human whether to:
 
 - proceed with existing/default Outrank settings for now, or
 - stop product creation until those settings are provided and/or configured elsewhere
@@ -223,8 +276,101 @@ Important behavior:
 - `cannibalization` highlights queries where multiple pages from the same site compete against each other.
 - Use `reconnect` when the status shows an expired token or refresh failure.
 - Use `disconnect` to remove the product's Search Console connection.
-
-## Keyword workflow
+
+## Linking workflow
+
+Use the product-scoped linking commands when the human needs to define where Outrank should discover internal-link candidates, inspect detected URLs, save a priority list, or constrain linking behavior.
+
+Recommended flow:
+
+1. Inspect current source settings with `outrank-cli products linking sources get <productId>`.
+2. Save or change the primary source with `outrank-cli products linking sources update <productId> --json-file linking-sources.json`.
+3. Re-run discovery with `outrank-cli products linking detect <productId>`.
+4. Review saved targets with `outrank-cli products linking targets list <productId>`.
+5. Add missing on-domain URLs with `outrank-cli products linking targets add-manual <productId> --json-file manual-target.json`.
+6. Prioritize or add anchor text with `outrank-cli products linking targets upsert <productId> --json-file target-upsert.json`.
+7. Inspect product-wide behavior with `outrank-cli products linking target-config get <productId>`.
+8. Enable or relax priority-only behavior with `outrank-cli products linking target-config update <productId> --json-file target-config.json`.
+9. Clear stale anchor-text overrides with `outrank-cli products linking targets clear-customizations <productId> <targetId>`.
+10. Delete stale targets with `outrank-cli products linking targets delete <productId> <targetId>`.
+
+Important behavior:
+
+- Linking writes are gated by the product's backlink subscription. If the API returns `subscription_management_url`, stop retrying and ask the human to manage that billing change in the dashboard.
+- `source_type` is not free-form. Use the exact backend values: `sitemap`, `root_url`, or `integration`.
+- `additional_linking_sources` is a replacement list, not a patch. Keep existing items you still want.
+- Manual and upserted target URLs must stay on the product's own domain.
+- `only_prioritized` may fail until enough prioritized targets exist. If the API returns a conflict, add or prioritize more URLs first.
+- `clear-customizations` only clears custom anchor text. It does not delete the target.
+
+## Backlinks workflow
+
+Use the product-scoped backlink commands when the human needs to inspect or change backlink exchange participation, review earned placements, work through unverified items, or inspect subscription state.
+
+Recommended flow:
+
+1. Inspect current settings with `outrank-cli products backlinks get <productId>`.
+2. Inspect credits with `outrank-cli products backlinks credits <productId>`.
+3. Review earned backlinks with `outrank-cli products backlinks earned <productId> --limit 20`.
+4. Add `--include-article` or `--include-summary` on the earned list when the human needs more article context.
+5. Review the unverified queue with `outrank-cli products backlinks unverified <productId> --limit 20`.
+6. Update settings with `outrank-cli products backlinks update <productId> --json-file backlinks.json`.
+7. Trigger a removal check with `outrank-cli products backlinks check-removal <productId> <backlinkId>`.
+8. Trigger a reverification with `outrank-cli products backlinks reverify <productId> <backlinkId>`.
+9. Inspect the current backlink subscription with `outrank-cli products backlinks subscription <productId>`.
+10. Quote a plan with `outrank-cli products backlinks subscribe-quote <productId> --plan premium|enterprise`.
+
+Important behavior:
+
+- Do not use `products update` for `backlinks_enabled` or `min_backlink_domain_rating`.
+- Backlink writes are blocked when the product is hidden for inappropriate content, but reads still work.
+- Setting `min_domain_rating` requires an active backlink subscription.
+- `subscribe-quote` is read-only. Purchasing or changing the add-on still requires dashboard checkout.
+- `earned` uses cursor pagination through `data.next_cursor`.
+- `unverified` is the deduped article-level manual-review stream.
+
+## Integrations workflow
+
+Use the current integrations commands when the human needs to inspect connected publishing integrations, validate direct credentials, run the WordPress.com or Notion OAuth handoff, inspect discovery data for Notion, Webflow, or Framer, test a saved integration row, or remove a stale one.
+
+Recommended flow:
+
+1. Inspect connected integrations with `outrank-cli products integrations list <productId>`.
+2. Inspect provider availability with `outrank-cli products integrations providers`.
+3. For webhook, ask only for `endpoint` and `access_token`. Outrank sends `Authorization: Bearer <access_token>` on each request. Do not ask for an HMAC secret because the current webhook integration does not implement HMAC signing.
+4. For WordPress Plugin, do not ask the human to invent or provide an `api_key`. Start with `outrank-cli products integrations prepare wordpress-plugin <productId>` to generate the integration token, then tell the human to paste that token into the installed plugin and save it in WordPress.
+5. For WordPress.com, start with `outrank-cli products integrations connect wordpress-com <productId> --json-file wordpress-com-connect.json`, tell the human to open the returned `connect_url`, then poll with `outrank-cli products integrations poll wordpress-com <productId> --attempt-id <attempt-id>` until the handoff completes.
+6. For Notion, start with `outrank-cli products integrations connect notion <productId>`, tell the human to open the returned `connect_url`, then poll with `outrank-cli products integrations poll notion <productId> --attempt-id <attempt-id>` until the handoff completes.
+7. After Notion OAuth completes, list databases with `outrank-cli products integrations notion databases <productId> <integrationId>`, inspect one schema with `... notion schema <productId> <integrationId> <databaseId>`, then update the saved integration row with `name`, `database_id`, and `fields`.
+8. For Shopify, start with `outrank-cli products integrations validate shopify --json '{"access_token":"shpat_xxx"}'`. The response returns `shop_name` and the available blogs, which the agent should use to build the create payload instead of guessing them or asking the human for the store name first.
+9. For Webflow, start with `outrank-cli products integrations validate webflow --json-file webflow-sites.json`, then use `webflow sites`, `webflow collections`, `webflow fields`, and `webflow items` to build the exact create or update payload for the chosen CMS collection.
+10. For Framer, use only the newer Server API flow. Start with `outrank-cli products integrations validate framer --json-file framer-validate.json`, then use `framer collections` and `framer fields` when the human wants to publish into an existing editable collection. Do not use or mention the older plugin-based setup.
+11. For Next.js Blog, do not ask the human for credentials first. Run `outrank-cli products integrations create <productId> --json '{"provider":"nextjs-blog"}'` and treat the returned `data.secrets.api_key` as a one-time secret that must be saved immediately.
+12. For Wix, use a direct credential flow with `site_id`, `api_key`, and `publish_status`. Validate first, then create or update directly; there is no OAuth or prepare step.
+13. Validate webhook, Ghost, Shopify, Webflow, Wix, Framer, or WordPress Plugin credentials before saving with `outrank-cli products integrations validate <provider> --json-file integration.json`.
+14. Create a webhook, Ghost, Shopify, Webflow, Wix, Framer, WordPress Plugin, or Next.js Blog integration with `outrank-cli products integrations create <productId> --json-file integration-create.json`.
+14. Inspect one row with `outrank-cli products integrations get <productId> <integrationId>`.
+15. Update a saved webhook, Ghost, Shopify, Webflow, Wix, WordPress Plugin, or Notion integration with `outrank-cli products integrations update <productId> <integrationId> --json-file integration-update.json`.
+16. Test a saved webhook, Ghost, Shopify, Webflow, Wix, Framer, WordPress Plugin, or Notion integration with `outrank-cli products integrations test <productId> <integrationId>`.
+17. If the integration is stale or wrong, remove it with `outrank-cli products integrations delete <productId> <integrationId>`.
+
+Important behavior:
+
+- V2 products are intended to keep exactly one publishing integration. If `list` returns multiple rows, treat the extras as likely legacy V1 leftovers and inspect before deleting.
+- `create` currently supports `webhook`, `ghost`, `shopify`, `webflow`, `wix`, `wordpress-plugin`, and `nextjs-blog` first. Other providers may appear in `providers`, but if their create/update/test capabilities are absent there, do not invent those writes.
+- `wordpress-plugin` should usually start with `prepare`, not with a question asking the human for an integration token. The prepare response includes the generated token plus suggested validate/create payloads.
+- `wordpress-com` should use `connect` plus `poll`, not `create`. The connect payload mirrors the dashboard flow with `name` and `publish_status`, then the human completes browser OAuth.
+- `notion` should use `connect` plus `poll`, not `create`. OAuth only stores the access token row. The agent still needs to list databases, inspect schema, and PATCH the saved row with `name`, `database_id`, and `fields` before the integration is publish-ready.
+- `shopify` should start with validation. The agent should not ask the human to guess `shop_name` or `blog_id` before `validate` returns them.
+- `webflow` should use validation plus discovery before create. The agent should not guess `site_id`, `collection_id`, or Webflow field mappings.
+- `framer` should use the newer Server API flow only. The agent should not mention the older Framer plugin flow. Validate the project URL and Server API key first, then use `framer collections` and `framer fields` only when the human chooses an existing editable collection. There is no separate plugin-config step in the agent surface.
+- `wix` uses direct validate/create/update/test with a site UUID plus API key. The agent should validate `site_id` and `api_key` before create or after credentials change.
+- `nextjs-blog` create returns a one-time API key. The agent must surface and preserve it immediately because later reads only show that a hash exists, not the plain secret.
+- deleting the current active integration clears the product integration fields automatically
+- `validate` tests unsaved credentials without persisting a row, while `test` re-checks a saved integration row
+- the current CLI surface still does not expose create, update, or test for some providers, and only WordPress.com and Notion currently expose an OAuth connect flow; if the human asks for unsupported operations, say they are not shipped in this CLI yet instead of inventing commands
+
+## Keyword workflow
 
 Keyword plans now have two buckets:
 
@@ -313,14 +459,15 @@ Inspect before mutating:
 
 Important behavior to remember:
 
-- article metadata and history mirror the current app behavior, including soft-delete instead of hard-delete
-- article bodies are markdown in the backend; `--format html` is rendered output, not the source of truth
-- featured image is separate from the markdown body and can be updated either through the normal article update payload via `image_url` or by local-file upload with `articles upload-featured-image`
-- in-content images can be uploaded from local files with `articles upload-image`; the command returns a hosted URL and alt text for markdown insertion or replacement
-- per-article instructions live on the linked scheduled keyword, so they are only editable while that planner relationship still exists and is writable
-- slug is readable for reference but read-only in the agent API
-- `articles generate <keywordId>` mirrors the current create-and-publish flow for a scheduled keyword
-- `articles precreate <keywordId>` mirrors the current pre-generation flow; after calling it, inspect the keyword state until it moves from `generating_article` to `pregenerated` or back to `scheduled`
+- article metadata and history mirror the current app behavior, including soft-delete instead of hard-delete
+- article bodies are markdown in the backend; `--format html` is rendered output, not the source of truth
+- featured image is separate from the markdown body and can be updated either through the normal article update payload via `image_url` or by local-file upload with `articles upload-featured-image`
+- in-content images can be uploaded from local files with `articles upload-image`; the command returns a hosted URL and alt text for markdown insertion or replacement
+- per-article instructions live on the linked scheduled keyword, so they are only editable while that planner relationship still exists and is writable
+- `articles update --json '{"status":"published"}'` attempts a real publish through the product's active integration for eligible attached articles; if the remote publish fails, inspect the returned error and the article's `publish_error`
+- slug is readable for reference but read-only in the agent API
+- `articles generate <keywordId>` mirrors the current create-and-publish flow for a scheduled keyword
+- `articles precreate <keywordId>` mirrors the current pre-generation flow; after calling it, inspect the keyword state until it moves from `generating_article` to `pregenerated` or back to `scheduled`
 - `articles retry-publish <articleId>` only works for generated articles with a publish error
 - `articles bulk-replace` is preview-first; review the returned excerpts, then rerun with `"confirm": true` in the JSON payload to write changes
 
@@ -342,7 +489,7 @@ Do not ask for billing approval until you have already clarified the intended pr
 - For `403` or `409`, the guidance usually tells you whether to inspect state, pause another product, or ask the human to approve a billing step.
 - For `402`, stop retrying and ask the human to fix billing.
 
-## Current limitation
-
-The implementation plan is broader than the current live API. Keywords and core article flows are now exposed in `outrank-cli`, but integrations, backlinks, and onboarding flows are still incomplete. If the user asks for something not present in `outrank-cli --help`, say that exact command surface is not shipped yet and do not invent unsupported commands.
+## Current limitation
+
+The implementation plan is broader than the current live API. Keywords, core article flows, linking, backlink exchange management, and the current integration-management flows are now exposed in `outrank-cli`, including direct setup for webhook, Ghost, Shopify, Webflow, Wix, Framer, WordPress Plugin, and Next.js Blog, plus OAuth flows for WordPress.com and Notion. Purchasing or changing backlink add-ons and some onboarding flows still require the dashboard. If the user asks for something not present in `outrank-cli --help`, say that exact command surface is not shipped yet and do not invent unsupported commands.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "outrank-cli",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Agent-first CLI for the Outrank agent API",
   "type": "module",
   "files": [