frontmost 0.0.0-stage → 0.6.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.
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
- # Temporary Holding Version
1
+ # Frontmost AI 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
+ 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 github:frontmost-ai/cli
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)
@@ -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
+ }