@softr/cli 0.1.2 → 0.1.4
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 +79 -34
- package/dist/cli.mjs +953 -525
- package/package.json +3 -2
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,54 +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
|
+
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
|
|
31
34
|
softr whoami # who the stored token belongs to and what it grants
|
|
32
35
|
softr logout
|
|
33
36
|
```
|
|
34
37
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
token needs a `workflows:*` action in its statements; `login` warns when it has none. `SOFTR_TOKEN` overrides the
|
|
38
|
-
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.
|
|
39
40
|
|
|
40
|
-
The CLI targets Softr production. For development, `SOFTR_WORKFLOWS_API_URL`, `SOFTR_STUDIO_API_URL
|
|
41
|
-
`SOFTR_STUDIO_URL` point it at
|
|
42
|
-
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.
|
|
43
43
|
|
|
44
44
|
## Global commands
|
|
45
45
|
|
|
46
|
-
| Command
|
|
47
|
-
|
|
|
48
|
-
| `login
|
|
49
|
-
| `workspaces`
|
|
50
|
-
| `integrations [--workspace <id>] [--type <TYPE>]`
|
|
51
|
-
|
|
52
|
-
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. |
|
|
53
51
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
The `softr workflows` commands; `softr workflows --help` lists them.
|
|
52
|
+
Every command accepts `--json`.
|
|
57
53
|
|
|
58
|
-
|
|
54
|
+
## Project folder
|
|
59
55
|
|
|
60
|
-
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:
|
|
61
59
|
|
|
62
60
|
```
|
|
63
61
|
my-project/
|
|
64
|
-
|
|
65
|
-
softr-workflows.jsonc # the workflow
|
|
66
|
-
actions/
|
|
67
|
-
|
|
68
|
-
score.py
|
|
69
|
-
.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)
|
|
70
66
|
weekly-digest/
|
|
71
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
|
|
72
89
|
```
|
|
73
90
|
|
|
74
91
|
#### `softr-workflows.jsonc`
|
|
@@ -154,7 +171,7 @@ node still on 1.0.0 or 1.1.0 keeps its synchronous runtime without `fetch`, and
|
|
|
154
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. |
|
|
155
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. |
|
|
156
173
|
|
|
157
|
-
|
|
174
|
+
After a `pull`, the workflow directory remembers its target in `.softr-workflows/state.json`.
|
|
158
175
|
|
|
159
176
|
Every `test` and `outputs --refresh` updates `.softr-workflows/outputs.json` and rewrites the code headers, so the
|
|
160
177
|
types of `inputData` follow the latest test data. Tests run against the server's copy of the workflow. `test` compares
|
|
@@ -188,6 +205,34 @@ softr workflows outputs score # variables the next no
|
|
|
188
205
|
softr workflows publish
|
|
189
206
|
```
|
|
190
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
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
| Command | What it does |
|
|
229
|
+
| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
230
|
+
| `db list` | The databases the token reaches, across all workspaces, with their workspace and number of tables. |
|
|
231
|
+
| `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. |
|
|
232
|
+
| `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`. |
|
|
233
|
+
| `db update [<databaseId>] [--name <name>] [--description <text>] [--dir <path>]` | Change the name, the description or both. |
|
|
234
|
+
| `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. |
|
|
235
|
+
|
|
191
236
|
## Agent skills
|
|
192
237
|
|
|
193
238
|
Two skills in the [Agent Skills](https://agentskills.io) format, published in
|