Skip to content

Commit 69288c5

Browse files
yosriadyyosriady
committed
Update CLI docs to latest
1 parent 8f3d7a0 commit 69288c5

9 files changed

Lines changed: 544 additions & 353 deletions

File tree

‎cli/alerts.mdx‎

Lines changed: 76 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -2,39 +2,40 @@
22
title: "Alerts"
33
sidebarTitle: "Alerts"
44
icon: bell
5-
description: "Manage project alerts from the terminal with the Formo CLI. Create, list, update, delete, and toggle alerts that notify you of key events and thresholds."
5+
description: "Manage project alerts from the terminal with the Formo CLI. Create, list, update, test, delete, and toggle alerts that notify your team about matching events or users."
66
---
77

8-
The `formo alerts` command group lets you manage project alerts. Alerts notify you when specific events or thresholds are triggered.
8+
The `formo alerts` command group manages project alerts. Alerts can notify email, Slack, or webhook recipients when event or user filters match.
99

1010
## `formo alerts list`
1111

12-
List all alerts for the project.
12+
List alerts for the active project.
1313

1414
<Note>
1515
Requires `alerts:read` scope on your API key.
1616
</Note>
1717

18+
### Options
19+
20+
| Option | Type | Required | Description |
21+
|--------|------|----------|-------------|
22+
| `--page` | `number` | ❌ | Page number, 1-indexed |
23+
| `--size` | `number` | ❌ | Page size |
24+
1825
```bash
19-
formo alerts list
26+
formo alerts list --size 25
2027
```
2128

2229
---
2330

24-
## `formo alerts get`
31+
## `formo alerts get <alertId>`
2532

2633
Get a single alert by ID.
2734

2835
<Note>
2936
Requires `alerts:read` scope on your API key.
3037
</Note>
3138

32-
### Arguments
33-
34-
| Argument | Type | Required | Description |
35-
|----------|------|----------|-------------|
36-
| `alertId` | `string` | ✅ | Alert ID |
37-
3839
```bash
3940
formo alerts get alert_abc123
4041
```
@@ -54,122 +55,133 @@ Requires `alerts:write` scope on your API key.
5455
| Option | Type | Required | Description |
5556
|--------|------|----------|-------------|
5657
| `--name` | `string` | ✅ | Alert name |
57-
| `--trigger-type` | `string` | ✅ | Trigger type (e.g. `event`, `threshold`) |
58+
| `--trigger-type` | `enum` | ✅ | Trigger type: `event` or `user` |
5859
| `--trigger-filters` | `string` | ❌ | JSON array of trigger filter objects |
5960
| `--recipient` | `string` | ❌ | JSON array of recipient objects |
6061
| `--secret` | `string` | ❌ | Webhook secret for the alert |
62+
| `--slack-property-keys` | `string` | ❌ | JSON array of event/user property keys to include in Slack alerts |
63+
64+
### Recipient Shape
65+
66+
`--recipient` is a JSON array. Each entry should include a `type` such as `email`, `slack`, or `webhook`, plus a `value`.
67+
68+
```json
69+
[
70+
{ "type": "email", "value": ["team@example.com"] },
71+
{ "type": "webhook", "value": ["https://example.com/formo-webhook"] }
72+
]
73+
```
6174

6275
### Examples
6376

6477
```bash
65-
# Create a basic event alert
6678
formo alerts create --name "High value tx" --trigger-type event
6779

68-
# Create an alert with trigger filters and recipients
6980
formo alerts create \
7081
--name "Whale activity" \
71-
--trigger-type threshold \
72-
--trigger-filters '[{"field":"net_worth_usd","op":"gt","value":100000}]' \
73-
--recipient '[{"type":"email","value":"team@example.com"}]'
82+
--trigger-type user \
83+
--trigger-filters '[{"name":"net_worth_usd","operator":"gt","value":100000}]' \
84+
--recipient '[{"type":"email","value":["team@example.com"]}]'
7485

75-
# Create an alert with a webhook secret
7686
formo alerts create \
77-
--name "Transaction webhook" \
87+
--name "Slack revenue alert" \
7888
--trigger-type event \
79-
--secret "whsec_abc123"
89+
--trigger-filters '[{"name":"revenue","operator":"gt","numericThreshold":1000}]' \
90+
--recipient '[{"type":"slack","value":["#alerts"]}]' \
91+
--slack-property-keys '["event","revenue","address"]'
8092
```
8193

8294
---
8395

84-
## `formo alerts update`
96+
## `formo alerts update <alertId>`
8597

8698
Update an existing alert.
8799

88100
<Note>
89101
Requires `alerts:write` scope on your API key.
90102
</Note>
91103

92-
### Arguments
93-
94-
| Argument | Type | Required | Description |
95-
|----------|------|----------|-------------|
96-
| `alertId` | `string` | ✅ | Alert ID to update |
104+
The API expects the full alert configuration, so provide the required alert fields again when updating.
97105

98106
### Options
99107

100108
| Option | Type | Required | Description |
101109
|--------|------|----------|-------------|
102-
| `--name` | `string` | ❌ | Alert name |
103-
| `--trigger-type` | `string` | ❌ | Trigger type |
110+
| `--name` | `string` | ✅ | Alert name |
111+
| `--trigger-type` | `enum` | ✅ | Trigger type: `event` or `user` |
104112
| `--trigger-filters` | `string` | ❌ | JSON array of trigger filter objects |
105113
| `--recipient` | `string` | ❌ | JSON array of recipient objects |
106114
| `--secret` | `string` | ❌ | Webhook secret for the alert |
107-
108-
### Examples
115+
| `--slack-property-keys` | `string` | ❌ | JSON array of event/user property keys to include in Slack alerts |
109116

110117
```bash
111-
# Update an alert name
112-
formo alerts update alert_abc123 --name "Renamed alert" --trigger-type event
113-
114-
# Update alert with new recipients
115118
formo alerts update alert_abc123 \
116-
--name "Updated alert" \
117-
--trigger-type threshold \
118-
--recipient '[{"type":"slack","value":"#alerts"}]'
119+
--name "Renamed alert" \
120+
--trigger-type event \
121+
--recipient '[{"type":"webhook","value":["https://example.com/formo-webhook"]}]'
119122
```
120123

121124
---
122125

123-
## `formo alerts delete`
126+
## `formo alerts toggle <alertId>`
124127

125-
Delete an alert.
128+
Toggle an alert status.
126129

127130
<Note>
128131
Requires `alerts:write` scope on your API key.
129132
</Note>
130133

131-
### Arguments
132-
133-
| Argument | Type | Required | Description |
134-
|----------|------|----------|-------------|
135-
| `alertId` | `string` | ✅ | Alert ID to delete |
134+
| Option | Type | Required | Description |
135+
|--------|------|----------|-------------|
136+
| `--status` | `enum` | ✅ | New status: `active` or `inactive`. `paused` is accepted as a deprecated alias for `inactive`. |
136137

137138
```bash
138-
formo alerts delete alert_abc123
139+
formo alerts toggle alert_abc123 --status inactive
140+
formo alerts toggle alert_abc123 --status active
139141
```
140142

141-
<Warning>
142-
Deleting an alert is permanent.
143-
</Warning>
144-
145143
---
146144

147-
## `formo alerts toggle`
145+
## `formo alerts test <alertId>`
148146

149-
Toggle an alert's status between `active` and `paused`.
147+
Send a test delivery for an alert.
150148

151149
<Note>
152150
Requires `alerts:write` scope on your API key.
153151
</Note>
154152

155-
### Arguments
156-
157-
| Argument | Type | Required | Description |
158-
|----------|------|----------|-------------|
159-
| `alertId` | `string` | ✅ | Alert ID to toggle |
160-
161153
### Options
162154

163155
| Option | Type | Required | Description |
164156
|--------|------|----------|-------------|
165-
| `--status` | `enum` | ✅ | New status: `active` or `paused` |
166-
167-
### Examples
157+
| `--sample-event` | `string` | ❌ | JSON object to use as the sample event |
158+
| `--sample-user` | `string` | ❌ | JSON object to use as the sample user/profile |
159+
| `--recipient-overrides` | `string` | ❌ | JSON array of recipient objects to test instead of saved recipients |
168160

169161
```bash
170-
# Pause an alert
171-
formo alerts toggle alert_abc123 --status paused
162+
formo alerts test alert_abc123 \
163+
--sample-event '{"event":"transaction","revenue":250}' \
164+
--recipient-overrides '[{"type":"email","value":["team@example.com"]}]'
165+
```
172166

173-
# Re-activate an alert
174-
formo alerts toggle alert_abc123 --status active
167+
<Note>
168+
Webhook tests require a public webhook URL. Localhost and private-network URLs are blocked by backend SSRF protections.
169+
</Note>
170+
171+
---
172+
173+
## `formo alerts delete <alertId>`
174+
175+
Delete an alert.
176+
177+
<Note>
178+
Requires `alerts:write` scope on your API key.
179+
</Note>
180+
181+
```bash
182+
formo alerts delete alert_abc123
175183
```
184+
185+
<Warning>
186+
Deleting an alert is permanent.
187+
</Warning>

‎cli/boards.mdx‎

Lines changed: 24 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ icon: table-columns
55
description: "Manage analytics dashboard boards from the terminal with the Formo CLI. Create, list, update, and delete boards that organize your charts and reports."
66
---
77

8-
The `formo boards` command group lets you manage dashboard boards for your project. Boards are containers for charts and can be used to organize your analytics dashboards.
8+
The `formo boards` command group manages dashboard boards for the active project. Boards are containers for charts.
99

1010
## `formo boards list`
1111

@@ -15,26 +15,27 @@ List all boards for the project.
1515
Requires `boards:read` scope on your API key.
1616
</Note>
1717

18+
### Options
19+
20+
| Option | Type | Required | Description |
21+
|--------|------|----------|-------------|
22+
| `--page` | `number` | ❌ | Page number, 1-indexed |
23+
| `--size` | `number` | ❌ | Page size |
24+
1825
```bash
19-
formo boards list
26+
formo boards list --size 25
2027
```
2128

2229
---
2330

24-
## `formo boards get`
31+
## `formo boards get <boardId>`
2532

2633
Get a single board by ID.
2734

2835
<Note>
2936
Requires `boards:read` scope on your API key.
3037
</Note>
3138

32-
### Arguments
33-
34-
| Argument | Type | Required | Description |
35-
|----------|------|----------|-------------|
36-
| `boardId` | `string` | ✅ | Board ID |
37-
3839
```bash
3940
formo boards get board_abc123
4041
```
@@ -53,72 +54,56 @@ Requires `boards:write` scope on your API key.
5354

5455
| Option | Type | Required | Description |
5556
|--------|------|----------|-------------|
56-
| `--name` | `string` | ✅ | Board name |
57+
| `--title` | `string` | ✅ | Board title |
58+
| `--name` | `string` | ❌ | Deprecated alias for `--title` |
5759
| `--description` | `string` | ❌ | Board description |
60+
| `--is-public` | `boolean` | ❌ | Whether the board is publicly viewable |
5861

5962
### Examples
6063

6164
```bash
62-
# Create a board
63-
formo boards create --name "KPI Dashboard"
64-
65-
# Create a board with a description
66-
formo boards create --name "Revenue Metrics" --description "Weekly revenue tracking"
65+
formo boards create --title "KPI Dashboard"
66+
formo boards create --title "Revenue Metrics" --description "Weekly revenue tracking" --is-public false
6767
```
6868

6969
---
7070

71-
## `formo boards update`
71+
## `formo boards update <boardId>`
7272

73-
Update an existing board.
73+
Update an existing board. Provide at least one updatable option.
7474

7575
<Note>
7676
Requires `boards:write` scope on your API key.
7777
</Note>
7878

79-
### Arguments
80-
81-
| Argument | Type | Required | Description |
82-
|----------|------|----------|-------------|
83-
| `boardId` | `string` | ✅ | Board ID to update |
84-
8579
### Options
8680

8781
| Option | Type | Required | Description |
8882
|--------|------|----------|-------------|
89-
| `--name` | `string` | ❌ | New board name |
83+
| `--title` | `string` | ❌ | New board title |
84+
| `--name` | `string` | ❌ | Deprecated alias for `--title` |
9085
| `--description` | `string` | ❌ | New board description |
91-
92-
### Examples
86+
| `--is-public` | `boolean` | ❌ | Whether the board is publicly viewable |
9387

9488
```bash
95-
# Rename a board
96-
formo boards update board_abc123 --name "Renamed Board"
97-
98-
# Update description
99-
formo boards update board_abc123 --description "Updated weekly metrics"
89+
formo boards update board_abc123 --title "Renamed Board"
90+
formo boards update board_abc123 --description "Updated weekly metrics" --is-public true
10091
```
10192

10293
---
10394

104-
## `formo boards delete`
95+
## `formo boards delete <boardId>`
10596

10697
Delete a board.
10798

10899
<Note>
109100
Requires `boards:write` scope on your API key.
110101
</Note>
111102

112-
### Arguments
113-
114-
| Argument | Type | Required | Description |
115-
|----------|------|----------|-------------|
116-
| `boardId` | `string` | ✅ | Board ID to delete |
117-
118103
```bash
119104
formo boards delete board_abc123
120105
```
121106

122107
<Warning>
123-
Deleting a board is permanent and will also remove all charts associated with it.
108+
Deleting a board is permanent and also removes its charts.
124109
</Warning>

0 commit comments

Comments
 (0)