@softr/cli 0.1.3 → 0.1.6-se21219.17
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/README.md +103 -37
- package/dist/cli.mjs +1758 -606
- package/package.json +4 -3
package/README.md
CHANGED
|
@@ -2,9 +2,12 @@
|
|
|
2
2
|
|
|
3
3
|
`softr` is the Softr command line: it works with your Softr workspace from files on your machine, by hand or through a
|
|
4
4
|
coding agent, and nothing runs locally. Its root commands cover the account and the workspace; each area of Softr is a
|
|
5
|
-
scope with a noun
|
|
6
|
-
|
|
7
|
-
|
|
5
|
+
scope with a noun:
|
|
6
|
+
|
|
7
|
+
- [`softr workflows`](#workflows): build, test and publish Softr workflows from local files.
|
|
8
|
+
- [`softr db`](#databases): manage Softr Databases.
|
|
9
|
+
|
|
10
|
+
More scopes follow.
|
|
8
11
|
|
|
9
12
|
Status: versions below 1.0 may change between releases; a single-binary build is planned.
|
|
10
13
|
|
|
@@ -21,56 +24,68 @@ its own.
|
|
|
21
24
|
|
|
22
25
|
## Log in
|
|
23
26
|
|
|
24
|
-
|
|
25
|
-
|
|
27
|
+
Log in through the browser (recommended) or with a personal API token. The CLI checks the token with Softr before it
|
|
28
|
+
stores it in `~/.softr/credentials.json`.
|
|
26
29
|
|
|
27
30
|
```bash
|
|
28
|
-
softr login # asks:
|
|
29
|
-
softr login --no-browser #
|
|
30
|
-
softr login --token
|
|
31
|
-
pbpaste | softr login --token # the same token from stdin, for scripts
|
|
31
|
+
softr login # asks: browser or personal API token
|
|
32
|
+
softr login --no-browser # prints the login URL to open elsewhere
|
|
33
|
+
pbpaste | softr login --token # a personal API token from stdin; without a pipe, it asks with the input hidden
|
|
32
34
|
softr whoami # who the stored token belongs to and what it grants
|
|
33
35
|
softr logout
|
|
34
36
|
```
|
|
35
37
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
token needs a `workflows:*` action in its statements; `login` warns when it has none. `--token` takes no value: a token
|
|
39
|
-
on the command line ends up in the shell history, so `login` reads it from stdin when piped and asks for it otherwise.
|
|
40
|
-
`SOFTR_TOKEN` overrides the stored token for scripts and CI. The studio session cookie is not accepted.
|
|
38
|
+
A personal API token needs the scopes of the commands you use: `workflows:*` for `softr workflows`, `databases.*` for
|
|
39
|
+
`softr db`. `SOFTR_TOKEN` overrides the stored token for scripts and CI.
|
|
41
40
|
|
|
42
|
-
The CLI targets Softr production. For development, `SOFTR_WORKFLOWS_API_URL`, `SOFTR_STUDIO_API_URL
|
|
43
|
-
`SOFTR_STUDIO_URL` point it at
|
|
44
|
-
ones. A workflow directory remembers the target it was pulled from.
|
|
41
|
+
The CLI targets Softr production. For development, `SOFTR_WORKFLOWS_API_URL`, `SOFTR_STUDIO_API_URL`,
|
|
42
|
+
`SOFTR_STUDIO_URL` and `SOFTR_TABLES_API_URL` point it at other Softr services.
|
|
45
43
|
|
|
46
44
|
## Global commands
|
|
47
45
|
|
|
48
|
-
| Command
|
|
49
|
-
|
|
|
50
|
-
| `login
|
|
51
|
-
| `workspaces`
|
|
52
|
-
| `integrations [--workspace <id>] [--type <TYPE>]`
|
|
53
|
-
|
|
54
|
-
Every command accepts `--json`. `SOFTR_TOKEN` overrides the stored token; `SOFTR_WORKSPACE_ID` is the default workspace.
|
|
46
|
+
| Command | What it does |
|
|
47
|
+
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
48
|
+
| `login` / `whoami` / `logout` | Log in, show who the stored token belongs to and what it grants, forget the token. |
|
|
49
|
+
| `workspaces` | The workspaces the token reaches, with your role and the scopes the token grants in each. Commands that take `--workspace` default to `SOFTR_WORKSPACE_ID`, else to your only or default workspace. |
|
|
50
|
+
| `integrations [--workspace <id>] [--type <TYPE>]` | The workspace's connected integrations: id, name, type and account. Credentials are never shown. |
|
|
55
51
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
The `softr workflows` commands; `softr workflows --help` lists them.
|
|
52
|
+
Every command accepts `--json`.
|
|
59
53
|
|
|
60
|
-
|
|
54
|
+
## Project folder
|
|
61
55
|
|
|
62
|
-
One directory holds exactly one workflow
|
|
56
|
+
One directory holds exactly one workflow or one database, with a `softr-*.jsonc` file that you own and commit, and a
|
|
57
|
+
dot directory where the CLI keeps its state and caches. A project folder groups related ones side by side, so you and
|
|
58
|
+
your agent can look up one from the other, for example the table and field ids a workflow reads:
|
|
63
59
|
|
|
64
60
|
```
|
|
65
61
|
my-project/
|
|
66
|
-
|
|
67
|
-
softr-workflows.jsonc # the workflow
|
|
68
|
-
actions/
|
|
69
|
-
|
|
70
|
-
score.py
|
|
71
|
-
.softr-workflows/ # CLI state: remote version/draft, cached sample outputs (gitignore it)
|
|
62
|
+
lead-scoring/
|
|
63
|
+
softr-workflows.jsonc # the workflow
|
|
64
|
+
actions/score.py # a Run custom code node
|
|
65
|
+
.softr-workflows/ # CLI state (gitignore it)
|
|
72
66
|
weekly-digest/
|
|
73
67
|
softr-workflows.jsonc
|
|
68
|
+
.softr-workflows/
|
|
69
|
+
crm/
|
|
70
|
+
softr-db.jsonc # names the database
|
|
71
|
+
.softr-db/schema.json # its tables and fields, kept current by the CLI (gitignore it)
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
`.gitignore` for the folder: `.softr-workflows/` and `.softr-db/`.
|
|
75
|
+
|
|
76
|
+
## Workflows
|
|
77
|
+
|
|
78
|
+
The `softr workflows` commands; `softr workflows --help` lists them.
|
|
79
|
+
|
|
80
|
+
### Workflow directory
|
|
81
|
+
|
|
82
|
+
```
|
|
83
|
+
lead-scoring/
|
|
84
|
+
softr-workflows.jsonc # the workflow (comments allowed)
|
|
85
|
+
actions/
|
|
86
|
+
enrich-record.js # body of the CUSTOM_CODE node "enrich-record"
|
|
87
|
+
score.py
|
|
88
|
+
.softr-workflows/ # CLI state: remote version/draft, cached sample outputs
|
|
74
89
|
```
|
|
75
90
|
|
|
76
91
|
#### `softr-workflows.jsonc`
|
|
@@ -156,7 +171,7 @@ node still on 1.0.0 or 1.1.0 keeps its synchronous runtime without `fetch`, and
|
|
|
156
171
|
| `workflows verify [--test-missing]` | One readiness report: code files parse, local files match the server, the service accepts the definition for publishing, every node tested on current data, every placeholder backed by test data. `--test-missing` first runs the tests that are missing, in execution order. Exit code 1 while something needs attention. |
|
|
157
172
|
| `workflows placeholder <nodeId> [keys...]` | Build the token for a node's output field from keys (`*` for every element, digits for an index, or one dotted path), checked against the saved test data: type and example when it exists, the keys that do exist when it does not. A loop id gives the current item. |
|
|
158
173
|
|
|
159
|
-
|
|
174
|
+
After a `pull`, the workflow directory remembers its target in `.softr-workflows/state.json`.
|
|
160
175
|
|
|
161
176
|
Every `test` and `outputs --refresh` updates `.softr-workflows/outputs.json` and rewrites the code headers, so the
|
|
162
177
|
types of `inputData` follow the latest test data. Tests run against the server's copy of the workflow. `test` compares
|
|
@@ -190,15 +205,66 @@ softr workflows outputs score # variables the next no
|
|
|
190
205
|
softr workflows publish
|
|
191
206
|
```
|
|
192
207
|
|
|
208
|
+
## Databases
|
|
209
|
+
|
|
210
|
+
The `softr db` commands manage Softr Databases through the
|
|
211
|
+
[Softr Database API](https://docs.softr.io/softr-api/softr-database-api); `softr db --help` lists them. Its
|
|
212
|
+
[rate limits](https://docs.softr.io/softr-api/softr-database-api/rate-limiting) apply per token.
|
|
213
|
+
|
|
214
|
+
### Database directory
|
|
215
|
+
|
|
216
|
+
`softr db create <name>` and `softr db get <id or name>` write `./<name-slug>/softr-db.jsonc` with the database id,
|
|
217
|
+
and `.softr-db/schema.json` next to it with the database, its tables and their fields (ids, names, types, options).
|
|
218
|
+
Inside that directory, or with `--dir <path>`, the commands work on that database without its id, and `db get` refreshes
|
|
219
|
+
the cache. A database id passed as an argument or in `SOFTR_DATABASE_ID` comes first. The commands that change the
|
|
220
|
+
schema refresh the cache too; the CLI rewrites it at any time, so never edit it.
|
|
221
|
+
|
|
222
|
+
```
|
|
223
|
+
crm/
|
|
224
|
+
softr-db.jsonc # { "databaseId": "…" }
|
|
225
|
+
.softr-db/schema.json # the cache of the tables and fields
|
|
226
|
+
.softr-db/views/<tableId>.json # the views of a table, once views list read them
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
| Command | What it does |
|
|
230
|
+
| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
231
|
+
| `db list` | The databases the token reaches, across all workspaces, with their workspace and number of tables. |
|
|
232
|
+
| `db get [<database>] [--dir <path>]` | One database with its tables, by id or exact name. Outside a database directory it creates `./<name-slug>/`; inside one it refreshes the cache, and a different database is an error. |
|
|
233
|
+
| `db create <name> [--description <text>] [--workspace <id>] [--dir <path>]` | Create an empty database and its directory. The workspace defaults to `SOFTR_WORKSPACE_ID`, else to your only or default workspace among those where the token grants `databases.schema:write`. |
|
|
234
|
+
| `db update [<databaseId>] [--name <name>] [--description <text>] [--dir <path>]` | Change the name, the description or both. |
|
|
235
|
+
| `db delete [<databaseId>] [--force] [--dir <path>]` | Delete a database. One that still has tables needs `--force`, which also deletes the tables and all their records. The directory keeps its `softr-db.jsonc`; the cache goes. |
|
|
236
|
+
| `db tables list` / `get <table>` | The tables of the database; one table with its fields (ids, types, primary/required/read-only). |
|
|
237
|
+
| `db tables create <name> [--field <name:TYPE>]... [--primary-field <name>]` | Create a table with at least one `--field`; the first one names a record. |
|
|
238
|
+
| `db tables update <table> [--name] [--description]` / `delete <table> [--force]` | Rename or describe a table; delete it (`--force` when it still has records). |
|
|
239
|
+
| `db fields get <table> <field>` | One field with its options. |
|
|
240
|
+
| `db fields add <table> <name> --type <TYPE> [--options <json>] [--multiple]` | Add a field. The types and their options: [field reference](https://docs.softr.io/softr-api/softr-database-api/table-fields/add-table-field). |
|
|
241
|
+
| `db fields update <table> <field> [--name] [--type] [--options <json>] [--[no-]multiple]` | Change a field; what is not passed stays as it is, `--options` replaces the options as a whole. |
|
|
242
|
+
| `db fields delete <table> <field>` | Delete a field and its values in every record. |
|
|
243
|
+
| `db views list <table>` | The views of a table (the API reads views only). |
|
|
244
|
+
| `db records list <table> [--view <view>] [--limit <n>] [--offset <n>] [--all]` | Records through a view, the table's default view unless `--view`; one page or `--all` in pages of 200. |
|
|
245
|
+
| `db records search <table> [--filter <json>] [--sort <field[:desc]>]...` | Records by a filter ([operators](https://docs.softr.io/softr-api/softr-database-api/records/search-records)); without `--filter`, every record. |
|
|
246
|
+
| `db records get <table> <recordId>` | One record. |
|
|
247
|
+
| `db records create <table> --fields <json>` / `update <table> <recordId> --fields <json>` | Create a record, or change some of its fields. `--fields` is inline JSON, `@<file>` or `-`. |
|
|
248
|
+
| `db records delete <table> <recordId>` | Delete a record. |
|
|
249
|
+
| `db records upload <table> <recordId> <field> <file> [--name <fileName>]` | Add a local file to an attachment field, stored under the local file name unless `--name`. |
|
|
250
|
+
|
|
251
|
+
Tables and fields take an id or an exact name; a name two items share is an error that lists their ids. The table,
|
|
252
|
+
field and view commands take the database from `--database <id>`, else `SOFTR_DATABASE_ID`, else the database
|
|
253
|
+
directory, and keep its cache current; a delete always resolves the name on the server, never from the cache.
|
|
254
|
+
Records are keyed by field name in the output and take field names in `--fields`, filters and `--sort`; the CLI maps
|
|
255
|
+
them to ids, which the API needs. `--field-ids` keys the output by id. Records are never written to disk.
|
|
256
|
+
|
|
193
257
|
## Agent skills
|
|
194
258
|
|
|
195
|
-
|
|
259
|
+
Three skills in the [Agent Skills](https://agentskills.io) format, published in
|
|
196
260
|
[softr-io/softr-io-skills](https://github.com/softr-io/softr-io-skills):
|
|
197
261
|
|
|
198
262
|
- [`softr-cli`](https://github.com/softr-io/softr-io-skills/tree/master/skills/softr-cli): install and update the CLI,
|
|
199
263
|
log in, the root commands and the environment variables. Every other Softr skill builds on it.
|
|
200
264
|
- [`softr-workflows`](https://github.com/softr-io/softr-io-skills/tree/master/skills/softr-workflows): the
|
|
201
265
|
`softr workflows` scope, with the code-file rules in its `references/custom-code.md`.
|
|
266
|
+
- [`softr-db`](https://github.com/softr-io/softr-io-skills/tree/master/skills/softr-db): the `softr db` scope, the
|
|
267
|
+
database directory and the schema commands.
|
|
202
268
|
|
|
203
269
|
Install them as a plugin in Claude Code, which keeps them updated, or with `npx skills add softr-io/softr-io-skills`
|
|
204
270
|
in every other agent. The exact steps are on [docs.softr.io/softr-cli](https://docs.softr.io/softr-cli).
|