outrank-cli 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +271 -19
  2. package/SKILL.md +168 -21
  3. package/package.json +1 -1
  4. package/src/commands/products.js +711 -2
  5. package/src/core/config.js +1 -1
  6. package/src/index.js +5 -1
package/README.md CHANGED
@@ -2,16 +2,52 @@
2
2
 
3
3
  Agent-first CLI for the Outrank agent API.
4
4
 
5
+ ## Install
6
+
7
+ Requires Node.js 18+. Works on macOS, Linux, and Windows.
8
+
9
+ ```bash
10
+ npm install -g outrank-cli
11
+ outrank-cli --help
12
+ ```
13
+
14
+ Or run it from a clone without installing globally:
15
+
16
+ ```bash
17
+ git clone https://github.com/Outrank-SAS/outrank-cli.git
18
+ cd outrank-cli
19
+ npm install
20
+ node ./src/index.js --help
21
+ ```
22
+
23
+ ## Get an API key
24
+
25
+ 1. Sign in to your Outrank account at <https://www.outrank.so>.
26
+ 2. Open **Settings → API keys**: <https://www.outrank.so/dashboard/settings/api-keys>.
27
+ 3. Click **Create key**, give it a name, and copy the `outr_live_...` value. The key is shown only once — store it somewhere safe.
28
+ 4. Revoke a key from the same page if it ever leaks. Generate a fresh one and re-run `auth login`.
29
+
30
+ You can also rotate keys at any time; each key is independent and can be revoked without affecting the others.
31
+
5
32
  ## Current scope
6
33
 
7
34
  This repo currently targets the agent endpoints that already exist in `outrank`:
8
35
 
9
36
  - `auth whoami`
10
37
  - `products list|get|create|update|pause|resume`
38
+ - `products integrations providers|prepare|connect|poll|validate|list|create|get|update|test|delete`
39
+ - `products integrations notion databases|schema`
40
+ - `products integrations framer collections|fields`
41
+ - `products integrations webflow sites|collections|fields|items`
11
42
  - `products output-settings get|update` for product article settings
12
43
  - `products target-audiences list|replace`
13
44
  - `products competitors list|replace`
14
45
  - `products gsc status|connect|poll|reconnect|disconnect|accounts|properties|set-property|performance|search-analytics|inspect-url|cannibalization`
46
+ - `products linking sources get|update`
47
+ - `products linking detect`
48
+ - `products linking target-config get|update`
49
+ - `products linking targets list|add-manual|upsert|clear-customizations|delete`
50
+ - `products backlinks get|update|credits|earned|unverified|check-removal|reverify|subscription|subscribe-quote`
15
51
  - `keywords list|get|export|generation-status|add|suggest|generate|reschedule|bulk-reschedule|delete|bulk-delete`
16
52
  - `articles list|get|get-content|update|update-content|replace|bulk-replace|upload-image|upload-featured-image|retry-publish|delete|precreate|generate`
17
53
  - `subscription status`
@@ -23,18 +59,39 @@ The broader roadmap from the internal implementation plan is larger than the liv
23
59
 
24
60
  ## Auth
25
61
 
26
- The CLI can read credentials from either:
62
+ The CLI reads credentials in this order of precedence:
27
63
 
28
- - `OUTRANK_API_KEY`
29
- - `~/.outrank/config.json` after `outrank-cli auth login <api-key>`
64
+ 1. `--api-key <key>` on the command line (highest priority, per-call)
65
+ 2. `OUTRANK_API_KEY` environment variable
66
+ 3. `~/.outrank/config.json`, populated by `outrank-cli auth login <api-key>` (lowest priority, persistent)
30
67
 
31
- Optional config storage override:
68
+ Pick one. For interactive use on your own machine, `auth login` is simplest. For CI / ephemeral environments, prefer the env var.
32
69
 
33
- - `OUTRANK_CONFIG_DIR`
70
+ ```bash
71
+ # One-time persistent setup
72
+ outrank-cli auth login outr_live_xxx
73
+ outrank-cli auth status # confirms the key is stored
74
+ outrank-cli auth whoami # round-trips it against the server
75
+
76
+ # OR per-shell env var (no config file written)
77
+ export OUTRANK_API_KEY="outr_live_xxx" # macOS / Linux (bash, zsh)
78
+ outrank-cli auth whoami
79
+
80
+ # OR per-call (useful in scripts)
81
+ outrank-cli auth whoami --api-key outr_live_xxx
82
+ ```
83
+
84
+ 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`.
85
+
86
+ Sign out / rotate:
87
+
88
+ ```bash
89
+ outrank-cli auth logout # clears apiKey from ~/.outrank/config.json
90
+ ```
34
91
 
35
92
  ## Examples
36
93
 
37
- ```powershell
94
+ ```bash
38
95
  outrank-cli auth login outr_live_xxx
39
96
  outrank-cli auth status
40
97
  outrank-cli auth whoami
@@ -46,8 +103,8 @@ outrank-cli articles get 00000000-0000-0000-0000-000000000000
46
103
  outrank-cli articles get-content 00000000-0000-0000-0000-000000000000 --format html
47
104
  outrank-cli articles update 00000000-0000-0000-0000-000000000000 --json '{"title":"New title"}'
48
105
  outrank-cli articles update 00000000-0000-0000-0000-000000000000 --json '{"image_url":"https://example.com/featured.jpg"}'
49
- outrank-cli articles upload-image --file .\diagram.png --article 00000000-0000-0000-0000-000000000000
50
- outrank-cli articles upload-featured-image 00000000-0000-0000-0000-000000000000 --file .\hero.jpg
106
+ outrank-cli articles upload-image --file ./diagram.png --article 00000000-0000-0000-0000-000000000000
107
+ outrank-cli articles upload-featured-image 00000000-0000-0000-0000-000000000000 --file ./hero.jpg
51
108
  outrank-cli articles replace 00000000-0000-0000-0000-000000000000 --json '{"find":"Old brand","replace_with":"New brand","preview_only":true}'
52
109
  outrank-cli articles retry-publish 00000000-0000-0000-0000-000000000000
53
110
  outrank-cli articles precreate 00000000-0000-0000-0000-000000000000
@@ -55,17 +112,54 @@ outrank-cli articles generate 00000000-0000-0000-0000-000000000000
55
112
  outrank-cli subscription status
56
113
  outrank-cli usage stats
57
114
  outrank-cli products get 00000000-0000-0000-0000-000000000000
115
+ outrank-cli products integrations providers
116
+ outrank-cli products integrations prepare wordpress-plugin 00000000-0000-0000-0000-000000000000
117
+ outrank-cli products integrations connect wordpress-com 00000000-0000-0000-0000-000000000000 --json '{"name":"Main WordPress.com","publish_status":"publish"}'
118
+ outrank-cli products integrations connect notion 00000000-0000-0000-0000-000000000000
119
+ outrank-cli products integrations poll wordpress-com 00000000-0000-0000-0000-000000000000 --attempt-id <attempt-id>
120
+ outrank-cli products integrations poll notion 00000000-0000-0000-0000-000000000000 --attempt-id <attempt-id>
121
+ outrank-cli products integrations notion databases 00000000-0000-0000-0000-000000000000 11111111-1111-1111-1111-111111111111
122
+ outrank-cli products integrations notion schema 00000000-0000-0000-0000-000000000000 11111111-1111-1111-1111-111111111111 aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
123
+ outrank-cli products integrations framer collections --json '{"project_url":"https://framer.com/projects/your-project","server_api_key":"framer_server_key"}'
124
+ 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"}'
125
+ outrank-cli products integrations webflow sites --json-file webflow-sites.json
126
+ outrank-cli products integrations webflow collections --json '{"api_token":"wf_token","site_id":"site_id"}'
127
+ outrank-cli products integrations webflow fields --json '{"api_token":"wf_token","collection_id":"collection_id"}'
128
+ outrank-cli products integrations webflow items --json '{"api_token":"wf_token","collection_id":"collection_id"}'
129
+ outrank-cli products integrations validate webhook --json '{"endpoint":"https://api.example.com/webhook","access_token":"secret"}'
130
+ outrank-cli products integrations validate framer --json '{"project_url":"https://framer.com/projects/your-project","server_api_key":"framer_server_key"}'
131
+ outrank-cli products integrations validate shopify --json '{"access_token":"shpat_xxx"}'
132
+ outrank-cli products integrations validate webflow --json '{"api_token":"wf_token"}'
133
+ outrank-cli products integrations validate wix --json '{"site_id":"00000000-0000-0000-0000-000000000000","api_key":"wix_api_key"}'
134
+ outrank-cli products integrations validate wordpress-plugin --json '{"domain":"https://example.com","api_key":"secret-token"}'
135
+ outrank-cli products integrations validate ghost --json '{"url":"https://example.ghost.io","api_key":"abcdef1234567890:abcdef1234567890abcdef1234567890"}'
136
+ outrank-cli products integrations list 00000000-0000-0000-0000-000000000000
137
+ 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"}'
138
+ 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"}'
139
+ 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"}'
140
+ 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"}'
141
+ outrank-cli products integrations create 00000000-0000-0000-0000-000000000000 --json-file webflow-create.json
142
+ outrank-cli products integrations create 00000000-0000-0000-0000-000000000000 --json '{"provider":"wordpress-plugin","domain":"https://example.com","api_key":"secret-token"}'
143
+ 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"}'
144
+ outrank-cli products integrations create 00000000-0000-0000-0000-000000000000 --json '{"provider":"nextjs-blog"}'
145
+ outrank-cli products integrations get 00000000-0000-0000-0000-000000000000 11111111-1111-1111-1111-111111111111
146
+ outrank-cli products integrations update 00000000-0000-0000-0000-000000000000 11111111-1111-1111-1111-111111111111 --json '{"endpoint":"https://api.example.com/webhook-v2"}'
147
+ outrank-cli products integrations update 00000000-0000-0000-0000-000000000000 11111111-1111-1111-1111-111111111111 --json '{"publish_status":"draft"}'
148
+ outrank-cli products integrations update 00000000-0000-0000-0000-000000000000 11111111-1111-1111-1111-111111111111 --json-file webflow-update.json
149
+ 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"}'
150
+ outrank-cli products integrations update 00000000-0000-0000-0000-000000000000 11111111-1111-1111-1111-111111111111 --json '{"publish_status":"published"}'
151
+ outrank-cli products integrations test 00000000-0000-0000-0000-000000000000 11111111-1111-1111-1111-111111111111
58
152
  outrank-cli keywords suggest --product 00000000-0000-0000-0000-000000000000 --theme "email marketing"
59
153
  outrank-cli keywords generate --product 00000000-0000-0000-0000-000000000000 --count 10 --source both
60
- outrank-cli keywords add --product 00000000-0000-0000-0000-000000000000 --json-file .\keywords.json
154
+ outrank-cli keywords add --product 00000000-0000-0000-0000-000000000000 --json-file ./keywords.json
61
155
  outrank-cli keywords export --product 00000000-0000-0000-0000-000000000000
62
- outrank-cli products create --json-file .\product.json
156
+ outrank-cli products create --json-file ./product.json
63
157
  # products create now auto-queues the initial ~30-day keyword plan; poll with keywords generation-status / keywords list
64
158
  outrank-cli billing portal-url
65
159
  outrank-cli products update 00000000-0000-0000-0000-000000000000 --json '{"daily_article_count":2}'
66
- outrank-cli products output-settings update 00000000-0000-0000-0000-000000000000 --json-file .\output-settings.json
67
- outrank-cli products target-audiences replace 00000000-0000-0000-0000-000000000000 --json-file .\target-audiences.json
68
- outrank-cli products competitors replace 00000000-0000-0000-0000-000000000000 --json-file .\competitors.json
160
+ outrank-cli products output-settings update 00000000-0000-0000-0000-000000000000 --json-file ./output-settings.json
161
+ outrank-cli products target-audiences replace 00000000-0000-0000-0000-000000000000 --json-file ./target-audiences.json
162
+ outrank-cli products competitors replace 00000000-0000-0000-0000-000000000000 --json-file ./competitors.json
69
163
  outrank-cli products gsc status 00000000-0000-0000-0000-000000000000
70
164
  outrank-cli products gsc connect 00000000-0000-0000-0000-000000000000
71
165
  outrank-cli products gsc poll 00000000-0000-0000-0000-000000000000 --attempt-id <attempt-id>
@@ -76,6 +170,24 @@ outrank-cli products gsc performance 00000000-0000-0000-0000-000000000000 --mont
76
170
  outrank-cli products gsc search-analytics 00000000-0000-0000-0000-000000000000 --dimensions query,page --limit 50 --query "brand"
77
171
  outrank-cli products gsc inspect-url 00000000-0000-0000-0000-000000000000 --url https://example.com/blog/post
78
172
  outrank-cli products gsc cannibalization 00000000-0000-0000-0000-000000000000
173
+ outrank-cli products linking sources get 00000000-0000-0000-0000-000000000000
174
+ outrank-cli products linking sources update 00000000-0000-0000-0000-000000000000 --json-file ./linking-sources.json
175
+ outrank-cli products linking detect 00000000-0000-0000-0000-000000000000
176
+ outrank-cli products linking target-config update 00000000-0000-0000-0000-000000000000 --json '{"only_prioritized":true}'
177
+ outrank-cli products linking targets list 00000000-0000-0000-0000-000000000000
178
+ outrank-cli products linking targets add-manual 00000000-0000-0000-0000-000000000000 --json-file ./manual-target.json
179
+ outrank-cli products linking targets upsert 00000000-0000-0000-0000-000000000000 --json-file ./target-upsert.json
180
+ outrank-cli products linking targets clear-customizations 00000000-0000-0000-0000-000000000000 11111111-1111-1111-1111-111111111111
181
+ outrank-cli products linking targets delete 00000000-0000-0000-0000-000000000000 11111111-1111-1111-1111-111111111111
182
+ outrank-cli products backlinks get 00000000-0000-0000-0000-000000000000
183
+ outrank-cli products backlinks update 00000000-0000-0000-0000-000000000000 --json '{"enabled":true,"min_domain_rating":10}'
184
+ outrank-cli products backlinks credits 00000000-0000-0000-0000-000000000000
185
+ outrank-cli products backlinks earned 00000000-0000-0000-0000-000000000000 --limit 10 --include-article
186
+ outrank-cli products backlinks unverified 00000000-0000-0000-0000-000000000000 --limit 10
187
+ outrank-cli products backlinks check-removal 00000000-0000-0000-0000-000000000000 11111111-1111-1111-1111-111111111111
188
+ outrank-cli products backlinks reverify 00000000-0000-0000-0000-000000000000 11111111-1111-1111-1111-111111111111
189
+ outrank-cli products backlinks subscription 00000000-0000-0000-0000-000000000000
190
+ outrank-cli products backlinks subscribe-quote 00000000-0000-0000-0000-000000000000 --plan premium
79
191
  outrank-cli keywords reschedule 00000000-0000-0000-0000-000000000000 --scheduled-for 2026-05-20
80
192
  outrank-cli billing purchase-products quote --additional-products 2
81
193
  ```
@@ -94,6 +206,69 @@ outrank-cli billing purchase-products quote --additional-products 2
94
206
  - Analyze overlapping-query cannibalization with `outrank-cli products gsc cannibalization <product-id>`.
95
207
  - Use `reconnect` when the token is expired and `disconnect` to remove the product connection.
96
208
 
209
+ ## Linking workflow
210
+
211
+ - Inspect current source selection with `outrank-cli products linking sources get <product-id>`.
212
+ - Update the primary or additional sources with `outrank-cli products linking sources update <product-id> --json-file linking-sources.json`.
213
+ - Re-run discovery with `outrank-cli products linking detect <product-id>`.
214
+ - List saved targets with `outrank-cli products linking targets list <product-id>`.
215
+ - Add a manual on-domain URL with `outrank-cli products linking targets add-manual <product-id> --json-file manual-target.json`.
216
+ - Create or update a saved target with `outrank-cli products linking targets upsert <product-id> --json-file target-upsert.json`.
217
+ - Inspect or update product-wide behavior with `outrank-cli products linking target-config get|update <product-id>`.
218
+ - Clear custom anchor text with `outrank-cli products linking targets clear-customizations <product-id> <target-id>`.
219
+ - Remove a stale target with `outrank-cli products linking targets delete <product-id> <target-id>`.
220
+
221
+ Example payloads:
222
+
223
+ ```json
224
+ {
225
+ "source_type": "sitemap",
226
+ "source_url": "https://example.com/sitemap.xml",
227
+ "additional_linking_sources": [
228
+ {
229
+ "id": "docs-root",
230
+ "source_type": "root_url",
231
+ "source_url": "https://docs.example.com/blog",
232
+ "purpose": "linking"
233
+ }
234
+ ]
235
+ }
236
+ ```
237
+
238
+ ```json
239
+ {
240
+ "url": "https://example.com/blog/best-page",
241
+ "title": "Best Page",
242
+ "is_prioritized": true,
243
+ "anchor_texts": [
244
+ "best page",
245
+ "example guide"
246
+ ]
247
+ }
248
+ ```
249
+
250
+ ## Backlinks workflow
251
+
252
+ - Inspect current backlink settings with `outrank-cli products backlinks get <product-id>`.
253
+ - Update backlink settings with `outrank-cli products backlinks update <product-id> --json-file backlinks.json`.
254
+ - Inspect current credits with `outrank-cli products backlinks credits <product-id>`.
255
+ - Review earned backlinks with `outrank-cli products backlinks earned <product-id> --limit 20`.
256
+ - Add `--include-article` or `--include-summary` when the human needs article context in the earned list.
257
+ - Review the unverified queue with `outrank-cli products backlinks unverified <product-id> --limit 20`.
258
+ - Trigger a live removal check with `outrank-cli products backlinks check-removal <product-id> <backlink-id>`.
259
+ - Trigger manual reverification with `outrank-cli products backlinks reverify <product-id> <backlink-id>`.
260
+ - Inspect the current backlink subscription state with `outrank-cli products backlinks subscription <product-id>`.
261
+ - Quote a dashboard-equivalent subscription plan with `outrank-cli products backlinks subscribe-quote <product-id> --plan premium`.
262
+
263
+ Example payload:
264
+
265
+ ```json
266
+ {
267
+ "enabled": true,
268
+ "min_domain_rating": 10
269
+ }
270
+ ```
271
+
97
272
  ## Keyword mutation rules
98
273
 
99
274
  - Run `outrank-cli keywords generation-status --product <product-id>` before keyword writes when you are not sure the product is writable.
@@ -111,22 +286,72 @@ outrank-cli billing purchase-products quote --additional-products 2
111
286
  - 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`.
112
287
  - 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.
113
288
  - 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.
289
+ - `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.
114
290
  - Slug is returned for read-only reference but cannot be changed through the agent API.
115
291
  - `articles generate <keyword-id>` is only valid for scheduled keywords due today; it mirrors the dashboard's create-and-publish action.
116
292
  - `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.
117
293
  - `articles update --json '{"status":"published"}'` cannot be used to manually publish a future scheduled article before its due date.
118
294
  - `articles retry-publish <article-id>` is only valid for generated articles with a publish error.
119
295
 
296
+ ## Linking behavior notes
297
+
298
+ - Linking writes are blocked unless the product has an active backlink subscription.
299
+ - `products linking sources update` accepts `source_type` values `sitemap`, `root_url`, or `integration`.
300
+ - When `source_type` is `sitemap` or `root_url`, `source_url` is required.
301
+ - `additional_linking_sources` is a full replacement list. Each item needs `id`, `source_type`, `source_url`, and `purpose`.
302
+ - `products linking detect` refreshes discovered article URLs from the saved primary source.
303
+ - `products linking targets add-manual` and `upsert` only accept URLs on the product's own domain.
304
+ - `products linking target-config update --json '{"only_prioritized":true}'` requires enough prioritized targets; if not, the API returns a conflict with guidance.
305
+
306
+ ## Backlink behavior notes
307
+
308
+ - Use `products backlinks update`, not `products update`, for backlink exchange settings.
309
+ - Backlink writes are blocked when the product is hidden for inappropriate content, but reads still work.
310
+ - Setting `min_domain_rating` requires an active backlink subscription.
311
+ - `products backlinks subscribe-quote` is read-only. Purchasing or changing the add-on still requires the dashboard checkout flow.
312
+ - `products backlinks earned` uses cursor pagination through `data.next_cursor`.
313
+ - `products backlinks unverified` is the deduped article-level manual-review stream.
314
+
315
+ ## Integrations workflow
316
+
317
+ - Inspect connected publishing integrations with `outrank-cli products integrations list <product-id>`.
318
+ - Inspect provider availability with `outrank-cli products integrations providers`.
319
+ - 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.
320
+ - WordPress Plugin uses `domain` plus `api_key`. The Outrank plugin must already be installed and configured on the target site.
321
+ - 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.
322
+ - 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.
323
+ - 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`.
324
+ - 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.
325
+ - 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.
326
+ - 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.
327
+ - 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.
328
+ - 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.
329
+ - Validate unsaved webhook, Ghost, Framer, Shopify, Webflow, Wix, or WordPress Plugin credentials with `outrank-cli products integrations validate <provider> --json-file integration.json`.
330
+ - 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`.
331
+ - Inspect one integration with `outrank-cli products integrations get <product-id> <integration-id>`.
332
+ - 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`.
333
+ - Test a saved webhook, Ghost, Framer, Shopify, Webflow, Wix, WordPress Plugin, or Notion integration with `outrank-cli products integrations test <product-id> <integration-id>`.
334
+ - Delete a stale integration with `outrank-cli products integrations delete <product-id> <integration-id>`.
335
+
336
+ Current scope note:
337
+
338
+ - 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.
339
+ - 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.
340
+ - 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.
341
+ - Other providers are still mostly read/delete only while create, update, test, and provider-specific discovery are added one by one.
342
+
120
343
  ## Custom API target (advanced)
121
344
 
122
- The CLI talks to `https://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.
345
+ 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.
123
346
 
124
- ```powershell
125
- $env:OUTRANK_BASE_URL="https://staging.example"
347
+ ```bash
348
+ export OUTRANK_BASE_URL="https://staging.example" # macOS / Linux
126
349
  outrank-cli auth whoami
127
350
  ```
128
351
 
129
- `--base-url <url>` is the per-command form.
352
+ On Windows PowerShell, use `$env:OUTRANK_BASE_URL = "https://staging.example"`. On Windows `cmd.exe`, use `set OUTRANK_BASE_URL=https://staging.example`.
353
+
354
+ `--base-url <url>` is the per-command form and works on every platform.
130
355
 
131
356
  The agent API expects product UUIDs, not numeric ids like `88`.
132
357
 
@@ -136,8 +361,8 @@ The agent API expects product UUIDs, not numeric ids like `88`.
136
361
 
137
362
  If you do not want a global link yet, you can run the CLI directly from this repo:
138
363
 
139
- ```powershell
140
- node .\src\index.js auth whoami --api-key outr_live_xxx
364
+ ```bash
365
+ node ./src/index.js auth whoami --api-key outr_live_xxx
141
366
  ```
142
367
 
143
368
  ## JSON-first contract
@@ -150,3 +375,30 @@ Every command writes a single JSON object to stdout.
150
375
 
151
376
  This makes the CLI easier for AI agents to drive reliably.
152
377
 
378
+ ## Using the agent skill (`SKILL.md`)
379
+
380
+ `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.
381
+
382
+ 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.
383
+
384
+ ### Claude Code
385
+
386
+ 1. Install `outrank-cli` globally so the agent can call it: `npm install -g outrank-cli`.
387
+ 2. Make `SKILL.md` available to Claude Code as a skill. Either:
388
+ - **Project-scoped** — copy `SKILL.md` into `.claude/skills/outrank/SKILL.md` inside the project you want the agent to work in, or
389
+ - **User-scoped** — copy it into `~/.claude/skills/outrank/SKILL.md` (Windows: `C:\Users\<you>\.claude\skills\outrank\SKILL.md`) so it is available in every Claude Code session.
390
+ 3. Provide the API key once via env var or `outrank-cli auth login` (see [Auth](#auth)).
391
+ 4. In Claude Code, ask the agent to do something Outrank-shaped (e.g. "list my products", "create a new product for example.com", "regenerate next week's keyword plan"). The skill's `description` triggers it automatically; Claude will run `outrank-cli` commands and follow the rules in `SKILL.md`.
392
+
393
+ ### Other agents (Cursor, custom Anthropic SDK apps, etc.)
394
+
395
+ `SKILL.md` is plain Markdown — feed it as a system prompt, a tool description, or load it into the model's context however your runtime expects. The key contract is:
396
+
397
+ - Every command returns JSON with `ok`, `data`, and `agent_guidance`.
398
+ - The agent should always read `agent_guidance` before deciding the next step.
399
+ - Mutations should be preceded by an inspect call (`products get`, `keywords list`, `articles get`, etc.).
400
+
401
+ ### Updating the skill
402
+
403
+ The CLI and `SKILL.md` are versioned together. When you upgrade `outrank-cli`, also refresh the copy of `SKILL.md` in your `.claude/skills/...` directory from the installed package (`<global node_modules>/outrank-cli/SKILL.md`) or from this repo.
404
+