frontmost 0.0.0-stage → 0.6.2
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.
- package/LICENSE +21 -0
- package/README.md +177 -2
- package/bin/frontmost.js +18 -0
- package/openapi.json +4676 -0
- package/package.json +36 -4
- package/src/cli.js +363 -0
- package/src/config.js +114 -0
- package/src/errors.js +13 -0
- package/src/help.js +140 -0
- package/src/home.js +113 -0
- package/src/http.js +67 -0
- package/src/oauth.js +228 -0
- package/src/output.js +108 -0
- package/src/spec.js +141 -0
- package/src/style.js +102 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Frontmost AI
|
|
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,178 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Frontmost AI CLI
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
See how AI apps answer your buyers' questions, from the terminal.
|
|
4
|
+
|
|
5
|
+
```console
|
|
6
|
+
$ frontmost
|
|
7
|
+
|
|
8
|
+
” frontmost Fieldnote · Scale
|
|
9
|
+
|
|
10
|
+
Fieldnote
|
|
11
|
+
Scan of Oct 5 · 31 answers · 6 AI apps
|
|
12
|
+
|
|
13
|
+
Visibility 32% ●●●●●●●●●●○○○○○○○○○○○○○○○○○○○○○ 10 of 31 ▲ 2 pts
|
|
14
|
+
Win rate 3% ●○○○○○○○○○○○○○○○○○○○○○○○○○○○○○○ 1 of 31 ▼ 10 pts
|
|
15
|
+
Position 2.4 average place when named · was 2
|
|
16
|
+
|
|
17
|
+
Named most
|
|
18
|
+
1 Waypoint Notes 18 of 31
|
|
19
|
+
2 Trailbook 16 of 31
|
|
20
|
+
3 Inkfield 15 of 31
|
|
21
|
+
⋮
|
|
22
|
+
5 You 10 of 31
|
|
23
|
+
|
|
24
|
+
Next frontmost rivals · frontmost answers · frontmost --help
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Run `frontmost` with no command to see your latest scan. Each dot is one answer. A filled dot is an answer that named you. The example uses sample data.
|
|
28
|
+
|
|
29
|
+
## Install
|
|
30
|
+
|
|
31
|
+
On macOS or Linux:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
curl -fsSL https://frontmost.ai/install | bash
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
The installer downloads one program for your system, checks its checksum, and puts it in `~/.frontmost/bin`. It needs nothing else.
|
|
38
|
+
|
|
39
|
+
With Homebrew:
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
brew install frontmost-ai/tap/frontmost
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
With npm (Node.js 22.12 or later):
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
npm install -g frontmost
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Sign in
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
frontmost login
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Your browser opens. Sign in there, and the CLI is ready. You stay signed in until `frontmost logout`.
|
|
58
|
+
|
|
59
|
+
On a computer with no browser, such as one that you reach over SSH, run `frontmost login --no-browser`. It shows a code to enter on any device.
|
|
60
|
+
|
|
61
|
+
In scripts and CI, create an API key on the [Team page](https://app.frontmost.ai/team) and set `FRONTMOST_API_KEY`.
|
|
62
|
+
|
|
63
|
+
## Commands
|
|
64
|
+
|
|
65
|
+
**Read.** Any key works.
|
|
66
|
+
|
|
67
|
+
```
|
|
68
|
+
frontmost whoami Your workspace, plan, and limits
|
|
69
|
+
frontmost projects Your projects
|
|
70
|
+
frontmost projects get One project
|
|
71
|
+
frontmost scans Delivered scans, newest first
|
|
72
|
+
frontmost metrics Visibility, Win Rate, Position, and Sentiment
|
|
73
|
+
frontmost rivals Rivals that the answers named
|
|
74
|
+
frontmost sources Sites that the answers cited, with each site's channel
|
|
75
|
+
frontmost answers Answers in a scan
|
|
76
|
+
frontmost answers get <id> One answer, with its text and citations
|
|
77
|
+
frontmost questions The questions that Frontmost AI asks
|
|
78
|
+
frontmost profiles Your buyer profiles
|
|
79
|
+
frontmost recommendations What to do next
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
**Change.** Needs a Read and Write key.
|
|
83
|
+
|
|
84
|
+
```
|
|
85
|
+
frontmost projects create <domain> Start tracking a website. Add --apps, --cadence, or --no-weekly-brief
|
|
86
|
+
frontmost projects update Rename a project, or change its AI apps, cadence, or weekly brief
|
|
87
|
+
frontmost questions add "<question>"... Add questions
|
|
88
|
+
frontmost questions update <id> Reword or move a question
|
|
89
|
+
frontmost questions pause <id> Pause a question. It keeps its history and uses no credits
|
|
90
|
+
frontmost questions resume <id> Ask a paused question again
|
|
91
|
+
frontmost profiles add <name> Add a buyer profile
|
|
92
|
+
frontmost profiles update <id> Rename or describe a buyer profile
|
|
93
|
+
frontmost profiles remove <id> Remove a buyer profile
|
|
94
|
+
frontmost recommendations done <id> Mark a recommendation done
|
|
95
|
+
frontmost recommendations dismiss <id> Dismiss a recommendation
|
|
96
|
+
frontmost recommendations reopen <id> Open a recommendation again
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
`frontmost <command> --help` shows the options of one command.
|
|
100
|
+
|
|
101
|
+
## Examples
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
# This week against last week, unbranded questions only
|
|
105
|
+
frontmost metrics --period week --questions unbranded
|
|
106
|
+
|
|
107
|
+
# ChatGPT answers that did not name you
|
|
108
|
+
frontmost answers --app chatgpt --no-named
|
|
109
|
+
|
|
110
|
+
# Ask ChatGPT and Gemini on Monday, Wednesday, and Friday. The reply's run_config.cost.monthly_max is the most credits a month
|
|
111
|
+
frontmost projects update --apps chatgpt,gemini --cadence mwf --json
|
|
112
|
+
|
|
113
|
+
# Review sites that the answers cited
|
|
114
|
+
frontmost sources --channel review_sites
|
|
115
|
+
|
|
116
|
+
# Add two questions under one topic
|
|
117
|
+
frontmost questions add "Which CRM is best for agencies?" "Which CRM has the best reporting?" --topic CRM
|
|
118
|
+
|
|
119
|
+
# Pause a question
|
|
120
|
+
frontmost questions update 412 --no-active
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
## Projects
|
|
124
|
+
|
|
125
|
+
With one project, there is nothing to set. With more, name the project:
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
frontmost metrics --project 12
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Or set `FRONTMOST_PROJECT`. `frontmost projects` lists the IDs.
|
|
132
|
+
|
|
133
|
+
`frontmost projects create` takes a few minutes while Frontmost AI reads the website and writes the first questions. It waits, then prints the project. Add `--no-wait` to return at once.
|
|
134
|
+
|
|
135
|
+
## AI agents and scripts
|
|
136
|
+
|
|
137
|
+
| | |
|
|
138
|
+
| --- | --- |
|
|
139
|
+
| Sign in | Set `FRONTMOST_API_KEY`. Or ask the person to run `frontmost login` one time. |
|
|
140
|
+
| Output | Add `--json`. You get the API response, unchanged. |
|
|
141
|
+
| Paging | Add `--all` to get every page of a list. |
|
|
142
|
+
| Errors | With `--json`, errors are JSON on stderr, with a `code` and a `request_id`. |
|
|
143
|
+
| Exit codes | `0` success. `1` API or network error. `2` wrong command or option. |
|
|
144
|
+
| Any route | `frontmost api [METHOD] <path>` calls the [API](https://app.frontmost.ai/docs/api.md) directly. |
|
|
145
|
+
|
|
146
|
+
Without `--json`, output is a table on a terminal and tab-separated text in a pipe.
|
|
147
|
+
On a terminal, a rate shows its counts: `16% (4/25)`. In a pipe, the counts are separate columns, such as `visibility.numerator`.
|
|
148
|
+
In a pipe, one object is one `key<tab>value` line per field, and long text is on one line.
|
|
149
|
+
`frontmost` with no command prints the help in a pipe or with `--json`. Only a terminal gets the scan screen.
|
|
150
|
+
Color is off in a pipe, with `NO_COLOR`, and with `TERM=dumb`. `FORCE_COLOR=1` turns it on.
|
|
151
|
+
|
|
152
|
+
## How the CLI signs in
|
|
153
|
+
|
|
154
|
+
The CLI uses the first of these that it finds:
|
|
155
|
+
|
|
156
|
+
1. `--api-key`
|
|
157
|
+
2. `FRONTMOST_API_KEY` in the environment
|
|
158
|
+
3. `FRONTMOST_API_KEY` in `.env` in the current folder
|
|
159
|
+
4. The sign-in that `frontmost login` saved
|
|
160
|
+
|
|
161
|
+
A browser sign-in can read and change, the same as you can in the app. To give a script less, use a Read key.
|
|
162
|
+
|
|
163
|
+
`frontmost login --with-key` saves an API key in place of a browser sign-in.
|
|
164
|
+
|
|
165
|
+
The CLI never prints a key or a sign-in. `frontmost logout` removes the saved copy. More in [SECURITY.md](SECURITY.md).
|
|
166
|
+
|
|
167
|
+
## Contributing
|
|
168
|
+
|
|
169
|
+
```bash
|
|
170
|
+
npm install
|
|
171
|
+
npm test
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
Commands and options come from [`openapi.json`](openapi.json), a copy of the live API description. `npm run check-spec -- --write` updates it.
|
|
175
|
+
|
|
176
|
+
## License
|
|
177
|
+
|
|
178
|
+
[MIT](LICENSE)
|
package/bin/frontmost.js
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
const [major, minor] = process.versions.node.split(".").map(Number);
|
|
3
|
+
if (major < 22 || (major === 22 && minor < 12)) {
|
|
4
|
+
console.error(`Error: frontmost needs Node.js 22.12 or later. This is Node.js ${process.versions.node}.`);
|
|
5
|
+
process.exit(2);
|
|
6
|
+
}
|
|
7
|
+
|
|
8
|
+
// "frontmost answers --all | head" closes the pipe early. That is not an error.
|
|
9
|
+
process.stdout.on("error", (e) => process.exit(e.code === "EPIPE" ? 0 : 1));
|
|
10
|
+
|
|
11
|
+
try {
|
|
12
|
+
const { run } = await import("../src/cli.js");
|
|
13
|
+
process.exitCode = await run(process.argv.slice(2));
|
|
14
|
+
} catch (e) {
|
|
15
|
+
console.error(`Error: ${e instanceof Error ? e.message : e}`);
|
|
16
|
+
console.error("This is a fault in the CLI. Report it at https://github.com/frontmost-ai/cli/issues");
|
|
17
|
+
process.exitCode = 1;
|
|
18
|
+
}
|