@serpel/cli 0.0.0-stage → 0.1.1

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 (5) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +98 -2
  3. package/dist/THIRD_PARTY_LICENSES.txt +173 -0
  4. package/dist/index.js +491 -0
  5. package/package.json +60 -3
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Kerem Sinecek (Serpel, https://serpel.app)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,99 @@
1
- # Temporary Holding Version
1
+ # Serpel CLI
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Track Google rankings, audit your site, read Search Console and Bing data and check whether ChatGPT and Google AI Overviews cite you, all from your terminal. The CLI talks to the [Serpel](https://serpel.app) REST API and prints tables for people or JSON for scripts and coding agents.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ npm install -g @serpel/cli
9
+ ```
10
+
11
+ Requires Node.js 20.9 or newer. Run it once without installing:
12
+
13
+ ```bash
14
+ npx @serpel/cli --help
15
+ ```
16
+
17
+ ## Sign in
18
+
19
+ ```bash
20
+ serpel auth login
21
+ ```
22
+
23
+ The CLI opens a browser page where you confirm the sign-in with your Serpel account (device login). The token is stored in your system keyring (Windows Credential Manager, macOS Keychain or the Secret Service on Linux). If no keyring is available, it falls back to a file readable only by you.
24
+
25
+ In CI, create an API token in the dashboard under Settings, API tokens, and pass it on standard input:
26
+
27
+ ```bash
28
+ echo "$SERPEL_TOKEN" | serpel auth login --token-stdin
29
+ ```
30
+
31
+ No account yet? [Sign up for free](https://serpel.app/signup) and get free credits.
32
+
33
+ ## Examples
34
+
35
+ ```bash
36
+ serpel projects list
37
+ serpel projects create --domain example.com --country US --language en
38
+
39
+ serpel keywords research "rank tracker api" --country US --language en
40
+ serpel rankings add --project <id> --keyword "rank tracker api" --keyword "seo cli"
41
+ serpel rankings run --project <id>
42
+ serpel rankings list --project <id>
43
+
44
+ serpel crawl start --project <id> --wait
45
+ serpel audit issues --project <id>
46
+ serpel audit web-vitals <crawl-id>
47
+
48
+ serpel ai add --project <id> --prompt "best rank tracker with an API"
49
+ serpel ai status --project <id>
50
+
51
+ serpel search queries --project <id> --provider google --days 28
52
+ serpel monitoring recipients add --project <id> --email you@example.com
53
+
54
+ serpel billing balance
55
+ serpel export --project <id> --type rankings --format csv --output rankings.csv
56
+ ```
57
+
58
+ Every command supports `--json` for machine-readable output on stdout. Errors go to stderr, and exit codes tell you what went wrong, so the CLI works well in scripts and with coding agents such as Claude Code, Cursor and Codex.
59
+
60
+ ## Commands
61
+
62
+ | Group | What it does |
63
+ | --- | --- |
64
+ | `auth` | Sign in and out, show status and permissions |
65
+ | `projects` | List, create, update and delete projects, manage members |
66
+ | `keywords` | Keyword research by seed, list or domain, research history and lists |
67
+ | `rankings` | Track keywords, run rank checks, history, SERP details and summaries |
68
+ | `crawl` and `audit` | Start and compare crawls, issues, pages and Core Web Vitals |
69
+ | `ai` | Track prompts and see whether ChatGPT and Google AI Overviews cite you |
70
+ | `search` | Google Search Console and Bing Webmaster Tools data |
71
+ | `analytics` | Web analytics from PostHog, Plausible and Google Analytics 4 |
72
+ | `competitors` | Compare visibility with your competitors |
73
+ | `monitoring` and `reports` | Scheduled monitoring, email reports and webhooks |
74
+ | `recommendations` and `tasks` | Prioritised fixes and your task list |
75
+ | `scan` | Upload a snapshot of a Next.js codebase so routes map to live pages |
76
+ | `billing` and `providers` | Credits, estimates, usage and subscription |
77
+ | `tokens` and `agents` | API tokens and credit limits for AI agents |
78
+ | `export` | Issues, keywords, rankings or tasks as CSV or JSON |
79
+
80
+ Run `serpel <command> --help` for all options.
81
+
82
+ ## Configuration
83
+
84
+ | Setting | How |
85
+ | --- | --- |
86
+ | API URL | `--api-url`, `SERPEL_API_URL` or `serpel config set api-url <url>`; defaults to `https://serpel.app` |
87
+ | Colours | `--no-color` or `NO_COLOR=1` |
88
+ | Debugging | `--verbose` logs requests and status codes to stderr, never your token |
89
+
90
+ ## Links
91
+
92
+ - Documentation: https://serpel.app/docs/cli
93
+ - REST API: https://serpel.app/docs/api
94
+ - MCP server for coding agents: https://serpel.app/developers/mcp
95
+ - Pricing: https://serpel.app/pricing
96
+
97
+ ## License
98
+
99
+ MIT. The bundled third-party packages and their licenses are listed in `dist/THIRD_PARTY_LICENSES.txt`.
package/dist/THIRD_PARTY_LICENSES.txt ADDED
@@ -0,0 +1,173 @@
1
+ @serpel/cli 0.1.1 bundles the following third-party packages. Their license notices follow.
2
+
3
+ ------------------------------------------------------------------------
4
+
5
+ commander@15.0.0 (MIT)
6
+
7
+ (The MIT License)
8
+
9
+ Copyright (c) 2011 TJ Holowaychuk <tj@vision-media.ca>
10
+
11
+ Permission is hereby granted, free of charge, to any person obtaining
12
+ a copy of this software and associated documentation files (the
13
+ 'Software'), to deal in the Software without restriction, including
14
+ without limitation the rights to use, copy, modify, merge, publish,
15
+ distribute, sublicense, and/or sell copies of the Software, and to
16
+ permit persons to whom the Software is furnished to do so, subject to
17
+ the following conditions:
18
+
19
+ The above copyright notice and this permission notice shall be
20
+ included in all copies or substantial portions of the Software.
21
+
22
+ THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
23
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
24
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
25
+ IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
26
+ CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
27
+ TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
28
+ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
29
+
30
+ ------------------------------------------------------------------------
31
+
32
+ dom-serializer@3.1.1 (MIT)
33
+
34
+ Copyright © 2022 The Cheerio contributors
35
+
36
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
37
+
38
+ The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
39
+
40
+ THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
41
+
42
+ ------------------------------------------------------------------------
43
+
44
+ domelementtype@3.0.0 (BSD-2-Clause)
45
+
46
+ Copyright (c) Felix Böhm
47
+ All rights reserved.
48
+
49
+ Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
50
+
51
+ Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
52
+
53
+ Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
54
+
55
+ THIS IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS,
56
+ EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
57
+
58
+ ------------------------------------------------------------------------
59
+
60
+ domhandler@6.0.1 (BSD-2-Clause)
61
+
62
+ Copyright (c) Felix Böhm
63
+ All rights reserved.
64
+
65
+ Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
66
+
67
+ Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
68
+
69
+ Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
70
+
71
+ THIS IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS,
72
+ EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
73
+
74
+ ------------------------------------------------------------------------
75
+
76
+ domutils@4.0.2 (BSD-2-Clause)
77
+
78
+ Copyright (c) Felix Böhm
79
+ All rights reserved.
80
+
81
+ Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
82
+
83
+ Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
84
+
85
+ Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
86
+
87
+ THIS IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS,
88
+ EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
89
+
90
+ ------------------------------------------------------------------------
91
+
92
+ entities@8.1.0 (BSD-2-Clause)
93
+
94
+ Copyright (c) Felix Böhm
95
+ All rights reserved.
96
+
97
+ Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
98
+
99
+ Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
100
+
101
+ Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
102
+
103
+ THIS IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS,
104
+ EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
105
+
106
+ ------------------------------------------------------------------------
107
+
108
+ htmlparser2@12.0.0 (MIT)
109
+
110
+ Copyright 2010, 2011, Chris Winberry <chris@winberry.net>. All rights reserved.
111
+ Permission is hereby granted, free of charge, to any person obtaining a copy
112
+ of this software and associated documentation files (the "Software"), to
113
+ deal in the Software without restriction, including without limitation the
114
+ rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
115
+ sell copies of the Software, and to permit persons to whom the Software is
116
+ furnished to do so, subject to the following conditions:
117
+
118
+ The above copyright notice and this permission notice shall be included in
119
+ all copies or substantial portions of the Software.
120
+
121
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
122
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
123
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
124
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
125
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
126
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
127
+ IN THE SOFTWARE.
128
+
129
+ ------------------------------------------------------------------------
130
+
131
+ picocolors@1.1.1 (ISC)
132
+
133
+ ISC License
134
+
135
+ Copyright (c) 2021-2024 Oleksii Raspopov, Kostiantyn Denysov, Anton Verinov
136
+
137
+ Permission to use, copy, modify, and/or distribute this software for any
138
+ purpose with or without fee is hereby granted, provided that the above
139
+ copyright notice and this permission notice appear in all copies.
140
+
141
+ THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
142
+ WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
143
+ MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
144
+ ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
145
+ WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
146
+ ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
147
+ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
148
+
149
+ ------------------------------------------------------------------------
150
+
151
+ zod@4.6.5 (MIT)
152
+
153
+ MIT License
154
+
155
+ Copyright (c) 2025 Colin McDonnell
156
+
157
+ Permission is hereby granted, free of charge, to any person obtaining a copy
158
+ of this software and associated documentation files (the "Software"), to deal
159
+ in the Software without restriction, including without limitation the rights
160
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
161
+ copies of the Software, and to permit persons to whom the Software is
162
+ furnished to do so, subject to the following conditions:
163
+
164
+ The above copyright notice and this permission notice shall be included in all
165
+ copies or substantial portions of the Software.
166
+
167
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
168
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
169
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
170
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
171
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
172
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
173
+ SOFTWARE.