@lowdefy/docs-content 6.1.0 → 7.0.0
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 +1 -0
- package/content/actions/downloadcsv.md +1 -1
- package/content/actions/emailotpsend.md +58 -0
- package/content/actions/emailotpverify.md +79 -0
- package/content/actions/getlocalstorage.md +43 -0
- package/content/actions/link.md +47 -1
- package/content/actions/login.md +25 -5
- package/content/actions/logout.md +7 -5
- package/content/actions/magiclinkverify.md +117 -0
- package/content/actions/pdfmake.md +2 -2
- package/content/actions/posthogalias.md +29 -0
- package/content/actions/posthogcapture.md +49 -0
- package/content/actions/posthogcapturepageleave.md +38 -0
- package/content/actions/posthogfeatureflag.md +50 -0
- package/content/actions/posthoggroup.md +37 -0
- package/content/actions/posthogidentify.md +54 -0
- package/content/actions/posthoginit.md +96 -0
- package/content/actions/posthogoptin.md +29 -0
- package/content/actions/posthogoptout.md +29 -0
- package/content/actions/posthogpageview.md +37 -0
- package/content/actions/posthogreloadfeatureflags.md +47 -0
- package/content/actions/posthogreset.md +28 -0
- package/content/actions/posthogsetpersonproperties.md +36 -0
- package/content/actions/removelocalstorage.md +28 -0
- package/content/actions/resetvalidation.md +5 -3
- package/content/actions/setdarkmode.md +3 -3
- package/content/actions/setglobal.md +2 -0
- package/content/actions/setlocale.md +1 -1
- package/content/actions/setlocalstorage.md +34 -0
- package/content/actions/setstate.md +2 -0
- package/content/actions/validate.md +7 -4
- package/content/adapter-reference/mongodbauthadapter.md +46 -0
- package/content/agents/agent-endpoint-tools.md +24 -0
- package/content/agents/agent-properties.md +13 -3
- package/content/agents/agent-server-hooks.md +1 -1
- package/content/agents/agentchat.md +43 -7
- package/content/agents/agentconversations.md +42 -8
- package/content/agents/agents-introduction.md +107 -0
- package/content/callback-reference/auth0logoutcallback.md +54 -0
- package/content/concepts/ai-agent-docs.md +455 -106
- package/content/concepts/blocks.md +150 -0
- package/content/concepts/connections-and-requests.md +402 -0
- package/content/concepts/custom-html.md +42 -0
- package/content/concepts/custom-styling.md +50 -5
- package/content/concepts/dynamic-page-content.md +309 -0
- package/content/concepts/events-and-actions.md +154 -2
- package/content/concepts/four-primitives.md +31 -0
- package/content/concepts/html-attributes.md +293 -0
- package/content/concepts/i18n.md +8 -3
- package/content/concepts/keyboard-shortcuts.md +2 -2
- package/content/concepts/layout-overview.md +1 -1
- package/content/concepts/logger.md +99 -0
- package/content/concepts/lowdefy-api.md +1319 -0
- package/content/concepts/lowdefy-schema.md +136 -3
- package/content/concepts/menus.md +8 -7
- package/content/concepts/module-authoring.md +76 -5
- package/content/concepts/modules.md +3 -1
- package/content/concepts/notifications.md +180 -0
- package/content/concepts/operators.md +7 -0
- package/content/concepts/page-and-app-state.md +252 -0
- package/content/concepts/page-paths.md +209 -0
- package/content/concepts/theming.md +582 -0
- package/content/connections/aigateway.md +375 -0
- package/content/connections/anthropic.md +169 -2
- package/content/connections/awss3.md +178 -2
- package/content/connections/axioshttp.md +181 -0
- package/content/connections/google.md +169 -2
- package/content/connections/mongodb.md +1014 -3
- package/content/connections/openai-connection.md +169 -2
- package/content/connections/sendgridmail.md +2 -0
- package/content/connections/smtp.md +3 -1
- package/content/connections/treg.md +329 -0
- package/content/container-blocks/affix.md +47 -7
- package/content/container-blocks/alert.md +76 -24
- package/content/container-blocks/badge.md +100 -24
- package/content/container-blocks/box.md +9 -9
- package/content/container-blocks/card.md +132 -27
- package/content/container-blocks/carousel.md +60 -7
- package/content/container-blocks/collapse.md +153 -9
- package/content/container-blocks/configprovider.md +35 -13
- package/content/container-blocks/confirmmodal.md +69 -23
- package/content/container-blocks/content.md +62 -98
- package/content/container-blocks/descriptions.md +45 -4
- package/content/container-blocks/drawer.md +139 -28
- package/content/container-blocks/dropdownmenu.md +119 -31
- package/content/container-blocks/flex.md +40 -62
- package/content/container-blocks/footer.md +15 -11
- package/content/container-blocks/googlemapsheatmap.md +1 -1
- package/content/container-blocks/googlemapsscript.md +2 -2
- package/content/container-blocks/header.md +71 -36
- package/content/container-blocks/label.md +34 -7
- package/content/container-blocks/layout.md +52 -34
- package/content/container-blocks/masonry.md +17 -71
- package/content/container-blocks/mobilemenu.md +131 -88
- package/content/container-blocks/modal.md +161 -26
- package/content/container-blocks/pageheadermenu.md +138 -31
- package/content/container-blocks/pagesidebarlayout.md +230 -27
- package/content/container-blocks/pagesidermenu.md +153 -43
- package/content/container-blocks/popover.md +34 -31
- package/content/container-blocks/result.md +32 -21
- package/content/container-blocks/sider.md +85 -122
- package/content/container-blocks/span.md +7 -7
- package/content/container-blocks/spinner.md +3 -3
- package/content/container-blocks/splitter.md +150 -68
- package/content/container-blocks/tabs.md +64 -12
- package/content/container-blocks/tooltip.md +22 -46
- package/content/container-blocks/watermark.md +22 -4
- package/content/controls/parallel_for.md +21 -2
- package/content/controls/reject.md +24 -3
- package/content/controls/return.md +17 -1
- package/content/controls/throw.md +1 -0
- package/content/controls/try.md +4 -2
- package/content/controls/while.md +46 -0
- package/content/deployment/deployment-environments.md +10 -7
- package/content/deployment/docker.md +22 -7
- package/content/deployment/node-server.md +4 -0
- package/content/deployment/vercel.md +17 -6
- package/content/display-blocks/aggrid.md +33 -16
- package/content/display-blocks/anchor.md +16 -15
- package/content/display-blocks/avatar.md +57 -37
- package/content/display-blocks/breadcrumb.md +70 -21
- package/content/display-blocks/button.md +93 -19
- package/content/display-blocks/calendar.md +12 -0
- package/content/display-blocks/clickablehtml.md +239 -0
- package/content/display-blocks/dangeroushtml.md +1 -1
- package/content/display-blocks/difflist.md +1 -1
- package/content/display-blocks/difftimeline.md +1 -1
- package/content/display-blocks/divider.md +64 -3
- package/content/display-blocks/dropdownbutton.md +81 -30
- package/content/display-blocks/echart.md +35 -1
- package/content/display-blocks/eventlog.md +363 -0
- package/content/display-blocks/floatbutton.md +129 -42
- package/content/display-blocks/html.md +61 -1
- package/content/display-blocks/icon.md +250 -67
- package/content/display-blocks/img.md +2 -2
- package/content/display-blocks/menu.md +146 -73
- package/content/display-blocks/message.md +38 -124
- package/content/display-blocks/notification.md +94 -222
- package/content/display-blocks/paragraph.md +59 -9
- package/content/display-blocks/pollingtimer.md +263 -0
- package/content/display-blocks/progress.md +96 -17
- package/content/display-blocks/qrcode.md +19 -4
- package/content/display-blocks/s3download.md +1 -1
- package/content/display-blocks/search.md +19 -9
- package/content/display-blocks/skeletonbutton.md +1 -0
- package/content/display-blocks/skeletoninput.md +1 -0
- package/content/display-blocks/statistic.md +75 -17
- package/content/display-blocks/steps.md +58 -25
- package/content/display-blocks/table.md +2527 -0
- package/content/display-blocks/tablelight.md +621 -0
- package/content/display-blocks/tag.md +102 -17
- package/content/display-blocks/title.md +50 -11
- package/content/display-blocks/tour.md +33 -23
- package/content/input-blocks/autocomplete.md +81 -9
- package/content/input-blocks/buttonselector.md +45 -8
- package/content/input-blocks/captcha.md +40 -0
- package/content/input-blocks/checkboxselector.md +97 -7
- package/content/input-blocks/checkboxswitch.md +33 -3
- package/content/input-blocks/colorselector.md +63 -14
- package/content/input-blocks/daterangeselector.md +165 -45
- package/content/input-blocks/dateselector.md +139 -41
- package/content/input-blocks/datetimeselector.md +158 -49
- package/content/input-blocks/inputgallery.md +3 -3
- package/content/input-blocks/intentinput.md +207 -0
- package/content/input-blocks/monthselector.md +120 -52
- package/content/input-blocks/multipleselector.md +150 -39
- package/content/input-blocks/numberinput.md +98 -12
- package/content/input-blocks/pagination.md +70 -14
- package/content/input-blocks/paragraphinput.md +51 -37
- package/content/input-blocks/passwordinput.md +60 -6
- package/content/input-blocks/phonenumberinput.md +59 -26
- package/content/input-blocks/placesautocomplete.md +319 -0
- package/content/input-blocks/radioselector.md +83 -7
- package/content/input-blocks/ratingslider.md +57 -26
- package/content/input-blocks/s3uploadbutton.md +24 -24
- package/content/input-blocks/s3uploaddragger.md +3 -3
- package/content/input-blocks/s3uploadphoto.md +5 -5
- package/content/input-blocks/segmentedselector.md +72 -32
- package/content/input-blocks/selector.md +109 -21
- package/content/input-blocks/switch.md +65 -17
- package/content/input-blocks/tableinput.md +445 -0
- package/content/input-blocks/tagmultipleselector.md +114 -0
- package/content/input-blocks/tagselector.md +114 -0
- package/content/input-blocks/textarea.md +32 -3
- package/content/input-blocks/textinput.md +70 -29
- package/content/input-blocks/tiptapinput.md +1 -1
- package/content/input-blocks/tiptapmentioninput.md +2 -2
- package/content/input-blocks/titleinput.md +39 -12
- package/content/input-blocks/treeinput.md +49 -25
- package/content/input-blocks/treemultipleselector.md +127 -10
- package/content/input-blocks/treeselector.md +97 -9
- package/content/input-blocks/upload.md +64 -15
- package/content/input-blocks/uploaddragger.md +17 -1
- package/content/input-blocks/uploadphoto.md +18 -1
- package/content/input-blocks/weekselector.md +120 -55
- package/content/learn/introduction.md +27 -0
- package/content/learn/quickstart.md +53 -0
- package/content/learn/showcase.md +8 -0
- package/content/list-blocks/controlledlist.md +24 -15
- package/content/list-blocks/list.md +11 -11
- package/content/list-blocks/masonrylist.md +7 -34
- package/content/migration/auth-upgrade.md +337 -0
- package/content/migration/upgrade-guide.md +1 -0
- package/content/migration/v3-to-v4.md +417 -0
- package/content/migration/v6-to-v7.md +620 -0
- package/content/operators/_agent.md +155 -0
- package/content/operators/_app.md +2 -1
- package/content/operators/_array.md +122 -1
- package/content/operators/_build.md +1 -0
- package/content/operators/_credential.md +57 -0
- package/content/operators/_cron.md +292 -0
- package/content/operators/_date.md +2 -0
- package/content/operators/_error.md +24 -1
- package/content/operators/_get.md +6 -6
- package/content/operators/_hmac.md +78 -0
- package/content/operators/_js.md +2 -1
- package/content/operators/_location.md +1 -1
- package/content/operators/_media.md +13 -0
- package/content/operators/_module.md +56 -2
- package/content/operators/_operator.md +17 -3
- package/content/operators/_path_params.md +82 -0
- package/content/operators/_ref.md +258 -0
- package/content/operators/_request.md +1 -1
- package/content/operators/_request_details.md +6 -0
- package/content/operators/_type.md +14 -3
- package/content/operators/_url_query.md +2 -0
- package/content/operators/_user.md +3 -3
- package/content/plugins/plugins-actions.md +10 -0
- package/content/plugins/plugins-connections.md +25 -0
- package/content/plugins/plugins-dev.md +66 -0
- package/content/plugins/plugins-icon-sets.md +267 -0
- package/content/plugins/plugins-introduction.md +27 -1
- package/content/plugins/plugins.md +19 -0
- package/content/plugins/posthog.md +359 -0
- package/content/provider-reference/auth-js-providers.md +107 -0
- package/content/provider-reference/openidconnectprovider.md +44 -0
- package/content/recipes/recipes.md +16 -0
- package/content/reference/actions-reference.md +31 -0
- package/content/reference/blocks-reference.md +35 -0
- package/content/reference/cli.md +403 -0
- package/content/reference/connections-reference.md +23 -0
- package/content/reference/operators-reference.md +47 -0
- package/content/reference/reference.md +16 -0
- package/content/reference/schema-reference.md +12 -0
- package/content/testing/config-tests.md +677 -0
- package/content/testing/e2e-configuration.md +31 -1
- package/content/testing/e2e-getting-started.md +1 -1
- package/content/testing/e2e-introduction.md +1 -1
- package/content/testing/e2e-writing-tests.md +12 -1
- package/content/testing/explore-pull-request.md +136 -0
- package/content/testing/journey-data-sets.md +326 -0
- package/content/tutorial/tutorial-actions-operators.md +2 -2
- package/content/tutorial/tutorial-add-blocks.md +2 -2
- package/content/tutorial/tutorial-create-page.md +48 -2
- package/content/tutorial/tutorial-display-data-page.md +3 -3
- package/content/tutorial/tutorial-requests-api.md +155 -0
- package/content/tutorial/tutorial-requests-sql.md +153 -0
- package/content/tutorial/tutorial-start.md +66 -1
- package/content/user-authentication/auth-configuration.md +267 -0
- package/content/user-authentication/auth-providers.md +24 -0
- package/content/user-authentication/auth-steps.md +141 -0
- package/content/user-authentication/login-and-logout.md +160 -8
- package/content/user-authentication/mcp-oauth.md +424 -0
- package/content/user-authentication/organizations.md +246 -0
- package/content/user-authentication/protected-pages-apis.md +97 -0
- package/content/user-authentication/roles.md +49 -0
- package/content/user-authentication/two-factor.md +229 -0
- package/content/user-authentication/user-object.md +58 -0
- package/content/user-authentication/users-introduction.md +8 -0
- package/content/websockets/websocket-publish.md +105 -0
- package/content/websockets/websocket-subscriptions.md +136 -0
- package/content/websockets/websockets-introduction.md +101 -0
- package/hazards.json +56 -0
- package/index.json +3458 -14
- package/package.json +10 -1
- package/scripts/extractAgentDocs.js +41 -30
- package/scripts/hashDocSources.js +38 -0
- package/scripts/isRedirectPage.js +26 -0
- package/scripts/recordSourceHashes.js +97 -0
- package/scripts/resolvePageSections.js +42 -0
- package/scripts/sectionKind.js +27 -0
- package/content/concepts/cli.md +0 -223
- package/content/other/introduction.md +0 -39
- package/content/other/next-auth-providers.md +0 -3
- /package/content/{other → actions}/updatesession.md +0 -0
|
@@ -0,0 +1,403 @@
|
|
|
1
|
+
# The CLI
|
|
2
|
+
|
|
3
|
+
The Lowdefy CLI is used to develop a Lowdefy app locally, and to build Lowdefy apps for deployment.
|
|
4
|
+
|
|
5
|
+
We recommend running the CLI using `pnpx`, to always use the latest version:
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
pnpx lowdefy@5 <command>
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
or, to use a specific version:
|
|
12
|
+
|
|
13
|
+
```
|
|
14
|
+
pnpx lowdefy@version <command>
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Alternative, you can install the CLI globally or to a Javascript project (with a `package.json` file) via pnpm.
|
|
18
|
+
|
|
19
|
+
To install the CLI globally run:
|
|
20
|
+
|
|
21
|
+
```
|
|
22
|
+
pnpm add -g lowdefy
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
The CLI can then be run using `lowdefy` as the executable name:
|
|
26
|
+
|
|
27
|
+
```
|
|
28
|
+
lowdefy <command>
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
# CLI commands
|
|
32
|
+
|
|
33
|
+
## build
|
|
34
|
+
|
|
35
|
+
The `build` command runs a Lowdefy build. This builds a production Lowdefy app in the server directory, which can then be started using the `lowdefy start` command. The options are:
|
|
36
|
+
|
|
37
|
+
- `--config-directory <config-directory>`: Change the config directory. The default is the current working directory.
|
|
38
|
+
- `--disable-telemetry`: Disable telemetry.
|
|
39
|
+
- `--log-level <level>`: The minimum severity of logs to show in the CLI output. Options are `debug`, `info`, `warn` or `error`. The default is `info`.
|
|
40
|
+
- `--no-client-build`: Do not run the Vite client build, and only build the Lowdefy config. Used in some deployment scripts where the client build is done as a separate step. The previous `--no-next-build` flag still works as a deprecated alias.
|
|
41
|
+
- `--ref-resolver <ref-resolver-function-path>`: Path to a JavaScript file containing a `_ref` resolver function to be used as the app default `_ref` resolver.
|
|
42
|
+
- `--server-directory <server-directory>`: Change the server directory, the directory in which the production server is placed. The default is `<config-directory>/.lowdefy/server`.
|
|
43
|
+
- `--skip-codemod-check`: Suppress warnings about pending codemod upgrades.
|
|
44
|
+
- `--skip-plugin-checks`: Skip every [plugin build check rule](/lowdefy-schema#plugin-check-rules) for this run. Each build logs a warning that they were skipped. Built-in build checks still run. Use it while a fix ships for a plugin rule that is wrong or too strict.
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
## data list
|
|
48
|
+
|
|
49
|
+
The `data list` command prints each [journey data set](/journey-data-sets) in `tests/data/` with the number of documents it loads and the users it names.
|
|
50
|
+
|
|
51
|
+
- `--config-directory <config-directory>`: Change the config directory. The default is the current working directory.
|
|
52
|
+
- `--disable-telemetry`: Disable telemetry.
|
|
53
|
+
- `--log-level <level>`: The minimum severity of logs to show in the CLI output. Options are `debug`, `info`, `warn` or `error`. The default is `info`.
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
## dev
|
|
57
|
+
|
|
58
|
+
The `dev` command starts a Lowdefy development server, running locally. It can be accessed in a browser at [http://localhost:3000](http://localhost:3000). The CLI watches the file system, and rebuilds the app and reloads served pages every time a change is made to any of the files in the project directory. The `dev` command should not be used to serve a production app, the `build` and `start` commands should be used instead.
|
|
59
|
+
|
|
60
|
+
- `--config-directory <config-directory>`: Change the config directory. The default is the current working directory.
|
|
61
|
+
- `--dev-directory <dev-directory>`: Change the dev directory, the directory in which the development server is placed. The default is `<config-directory>/.lowdefy/dev`.
|
|
62
|
+
- `--disable-telemetry`: Disable telemetry.
|
|
63
|
+
- `--exit-with-pid <pid>`: Stop the server when the process with this id exits. For test runners and scripts that start the server. The `LOWDEFY_EXIT_WITH_PID` environment variable does the same, and passes through wrappers such as `pnpm exec` or a secrets manager.
|
|
64
|
+
- `--log-level <level>`: The minimum severity of logs to show in the CLI output. Options are `debug`, `info`, `warn` or `error`. The default is `info`.
|
|
65
|
+
- `--mock-user [user]`: Start the dev server authenticated as a mock user, bypassing the login flow. Pass a JSON user object to set the identity and roles (e.g. `--mock-user '{"sub":"dev","roles":["admin"]}'`), or use the bare flag for a default user with no roles. This is the same mechanism as `auth.dev.mockUser`. Dev server only. See [Auth Configuration](/auth-configuration#mock-user-for-testing-dev-server-only).
|
|
66
|
+
- `--no-open`: Do not open a new tab in the default browser.
|
|
67
|
+
- `--port <port>`: Change the port the server is hosted at. The default is `3000`. A port you set (with this option, the `PORT` environment variable, or `cli.port`) is used or the command fails; only the default moves to the next free port when it is taken.
|
|
68
|
+
- `--ref-resolver <ref-resolver-function-path>`: Path to a JavaScript file containing a `_ref` resolver function to be used as the app default `_ref` resolver.
|
|
69
|
+
- `--watch <paths...>`: A list of paths to files or directories that should be watched for changes. Globs are supported. Specify each path to watch separated by spaces.
|
|
70
|
+
- `--watch-ignore <patterns...>`: A list of paths to files or directories that should be ignored by the file watcher. Globs are supported. Specify each path to watch separated by spaces.
|
|
71
|
+
- `--skip-codemod-check`: Suppress warnings about pending codemod upgrades.
|
|
72
|
+
- `--skip-plugin-checks`: Skip every [plugin build check rule](/lowdefy-schema#plugin-check-rules) for this run. Each build logs a warning that they were skipped. Built-in build checks still run. Use it while a fix ships for a plugin rule that is wrong or too strict.
|
|
73
|
+
|
|
74
|
+
The server stops when the `lowdefy dev` process stops, however it stops, including when it is killed outright.
|
|
75
|
+
|
|
76
|
+
One app runs one dev server. The running server records itself in `.lowdefy/instance.json` (its pid, port, URL, state and whether a person or the [Lowdefy hub](#hub) started it), and a second `lowdefy dev` for the same app exits before touching anything, naming the server already running. A record copied from another checkout (for example into a git worktree) is ignored.
|
|
77
|
+
|
|
78
|
+
## emails
|
|
79
|
+
|
|
80
|
+
The `emails` command previews the [notification](/notifications) emails your app renders, using [React Email](https://react.email/)'s preview server. It builds the app, renders each notification from its `testData`, and opens the preview so you can iterate on templates without sending real mail. It warns when a template renders a data key your `testData` is missing (which would show as an empty section), and errors if the app has no `notifications:` section.
|
|
81
|
+
|
|
82
|
+
The preview tooling (`react-email`) is installed just-in-time by this command — it is never a dependency of your app or its production server.
|
|
83
|
+
|
|
84
|
+
- `--config-directory <config-directory>`: Change the config directory. The default is the current working directory.
|
|
85
|
+
- `--disable-telemetry`: Disable telemetry.
|
|
86
|
+
- `--log-level <level>`: The minimum severity of logs to show in the CLI output. Options are `debug`, `info`, `warn` or `error`. The default is `info`.
|
|
87
|
+
- `--port <port>`: Change the port the email preview server is hosted at. The default is `3001`.
|
|
88
|
+
- `--ref-resolver <ref-resolver-function-path>`: Path to a JavaScript file containing a `_ref` resolver function to be used as the app default `_ref` resolver.
|
|
89
|
+
- `--server-directory <server-directory>`: Change the server directory, the directory in which the production server is placed. The default is `<config-directory>/.lowdefy/server`.
|
|
90
|
+
|
|
91
|
+
## agent-setup
|
|
92
|
+
|
|
93
|
+
The `agent-setup` command sets up a project for AI coding agents. Run it as `npx lowdefy@<app version> agent-setup`. At the project root it writes `.mcp.json` registering the [`lowdefy` MCP server](/ai-agent-docs) — `lowdefy mcp`, run over stdio through npx at the version of the CLI running `agent-setup` — Lowdefy's guidance as a block between `<!-- BEGIN:lowdefy-agent-rules version=<version> -->` and `<!-- END:lowdefy-agent-rules -->` markers in `AGENTS.md` (or in `CLAUDE.md` when the project has only that), a root `CLAUDE.md` importing `@AGENTS.md`, and Lowdefy's skills in both `.agents/skills/` and `.claude/skills/`. Existing files are merged, not overwritten: each run rewrites only the block, and refreshes a skill only while neither of its two copies was edited. Nothing it writes names an app, so every app in a repository writes the same files. When the CLI's version differs from the app's, it still writes, and warns with the `npx lowdefy@<app version> agent-setup` command that matches them. It refuses apps on `lowdefy: local`. When several `package.json` scripts run `lowdefy dev`, it asks you to set [`cli.devScript`](#configuration). Before writing `.mcp.json` it runs the pinned version's `lowdefy mcp` through npx, and refuses a version npm cannot serve (unpublished, or from before `lowdefy mcp`); the refusal prints the `claude mcp add --scope local` command that runs your own build of the CLI for you only. See [Setting up a project](/ai-agent-docs).
|
|
94
|
+
|
|
95
|
+
- `--config-directory <config-directory>`: Change the config directory. The default is the current working directory.
|
|
96
|
+
- `--disable-telemetry`: Disable telemetry.
|
|
97
|
+
- `--log-level <level>`: The minimum severity of logs to show in the CLI output. Options are `debug`, `info`, `warn` or `error`. The default is `info`.
|
|
98
|
+
- `--project-directory <project-directory>`: Change the directory where agent files are written. The default is the nearest ancestor directory containing `.git`.
|
|
99
|
+
- `--user`: Instead of setting up this project, register `lowdefy mcp` as `lowdefy` for every Claude Code session of your user (`claude mcp add --scope user lowdefy -- npx ...`, or `cmd /c npx ...` on Windows), pinned to this CLI's version, replacing an earlier `lowdefy` or `lowdefy-docs` registration. Needs no app. The version must be published with `lowdefy mcp` (until Lowdefy 7 is released, `npx lowdefy@experimental agent-setup --user`). If the add fails, the existing registration stays and the error prints the commands to run. Without Claude Code on your `PATH`, it prints the entry to add to your agent client.
|
|
100
|
+
|
|
101
|
+
## mcp
|
|
102
|
+
|
|
103
|
+
The `mcp` command runs the Lowdefy MCP server for coding agents over stdio. Agent clients start it themselves from `.mcp.json` or their user configuration (see `agent-setup`), one per session — you do not run it by hand. It routes every tool call to the dev server of the app and git checkout the agent is working in, and starts that server through the [hub](#hub) when it is not running. See [AI agent docs](/ai-agent-docs).
|
|
104
|
+
|
|
105
|
+
## hub
|
|
106
|
+
|
|
107
|
+
The Lowdefy hub is a small per-user background process that runs dev servers for coding agents. `lowdefy mcp` starts it when an agent first needs a dev server, and it exits on its own after ten idle minutes. It gives each app its own port (from 4100 up, kept across restarts), runs the app's own dev script, and stops a server when no agent session has used it for 30 minutes and no browser tab has it open, or when its directory is removed. It only ever stops servers it started: a `lowdefy dev` you run in a terminal is used by agents but never stopped by them.
|
|
108
|
+
|
|
109
|
+
- `lowdefy hub status`: List the dev servers the hub runs.
|
|
110
|
+
- `lowdefy hub start [directory] [--restart] [--clean]`: Start (or return) an app's dev server through the hub. `--clean` deletes the build directory first.
|
|
111
|
+
- `lowdefy hub stop [directory] [--all]`: Stop a dev server the hub runs, or all of them.
|
|
112
|
+
- `lowdefy hub logs [directory] [--lines <n>] [--grep <text>]`: Print the recent output of a dev server the hub runs.
|
|
113
|
+
- `lowdefy hub ps`: List the Lowdefy servers running on this machine (dev and production servers started with the CLI), the process that owns each, and whether that owner is gone.
|
|
114
|
+
- `lowdefy hub prune [--kill]`: Stop Lowdefy servers whose owner is gone, such as a test server whose test run was killed. It only lists them unless `--kill` is passed. It also lists servers whose `lowdefy` CLI was left running after whatever started it was killed (for example a `pnpm exec` wrapper killed outright), and servers left running by an older Lowdefy version, in both cases only when nothing but package-manager wrappers is left above them, as well as a dev server's Vite process left running after an older dev server was killed. A server with a live owner (a terminal, a script still running, the hub) is never stopped. The hub prunes servers whose owner is gone each time it starts.
|
|
115
|
+
- `lowdefy hub trust [directory]`: Let `lowdefy mcp` start and query the dev servers of the git repository `directory` is in from any agent session, not only sessions started in it. It covers all of the repository's git worktrees. Run it yourself, in an interactive terminal: it refuses without one, so an agent cannot trust a repository. It refuses a directory outside git.
|
|
116
|
+
- `lowdefy hub untrust [directory]`: Undo `hub trust`. Also removes an entry whose directory is gone, given its old path.
|
|
117
|
+
- `lowdefy hub trusted`: List the trusted repositories by their git directory (`.../repo/.git`), marking those that are missing.
|
|
118
|
+
|
|
119
|
+
When a `package.json` in an app's checkout lists `lowdefy` but no `node_modules` up to the checkout root has it (a fresh git worktree, for example), `lowdefy hub start` and `lowdefy mcp` do not run its dev script; they answer with the install command to run, and where. See [AI agent docs](/ai-agent-docs).
|
|
120
|
+
|
|
121
|
+
The hub keeps its state in `~/.lowdefy/hub`, and running servers record themselves in `~/.lowdefy/servers` (set `LOWDEFY_HOME` to move both). It starts servers with the script `cli.devScript` names, or the one `package.json` script that runs `lowdefy dev`, so wrappers such as a secrets manager apply to agent-started servers too.
|
|
122
|
+
|
|
123
|
+
## init
|
|
124
|
+
|
|
125
|
+
The `init` command initializes a Lowdefy application. It creates the `lowdefy.yaml` and `.gitignore` in the working directory.
|
|
126
|
+
|
|
127
|
+
- `--disable-telemetry`: Disable telemetry.
|
|
128
|
+
- `--log-level <level>`: The minimum severity of logs to show in the CLI output. Options are `debug`, `info`, `warn` or `error`. The default is `info`.
|
|
129
|
+
|
|
130
|
+
## init-docker
|
|
131
|
+
|
|
132
|
+
The `init-docker` command initializes a Dockerfile in the config directory that can be used to build a Docker image of the Lowdefy app.
|
|
133
|
+
|
|
134
|
+
- `--config-directory <config-directory>`: Change the config directory. The default is the current working directory.
|
|
135
|
+
- `--disable-telemetry`: Disable telemetry.
|
|
136
|
+
- `--log-level <level>`: The minimum severity of logs to show in the CLI output. Options are `debug`, `info`, `warn` or `error`. The default is `info`.
|
|
137
|
+
|
|
138
|
+
## docker-output
|
|
139
|
+
|
|
140
|
+
The `docker-output` command assembles a minimal production runtime at `.lowdefy/docker` from an already-built app. It traces the server's runtime dependency graph and copies only the files the server actually imports, keeping the Docker image small. Run it after `lowdefy build`; the Dockerfile created by `init-docker` runs it for you.
|
|
141
|
+
|
|
142
|
+
- `--config-directory <config-directory>`: Change the config directory. The default is the current working directory.
|
|
143
|
+
- `--server-directory <server-directory>`: Change the server directory. The default is `.lowdefy/server` in the config directory.
|
|
144
|
+
- `--disable-telemetry`: Disable telemetry.
|
|
145
|
+
- `--log-level <level>`: The minimum severity of logs to show in the CLI output. Options are `debug`, `info`, `warn` or `error`. The default is `info`.
|
|
146
|
+
|
|
147
|
+
## init-vercel
|
|
148
|
+
|
|
149
|
+
The `init-vercel` command initializes the installation scripts needed to deploy an app on [Vercel](https://vercel.com). It creates a directory called deploy, and a script called vercel.install.sh. It also creates a README file with instructions on how to configure Vercel.
|
|
150
|
+
|
|
151
|
+
- `--config-directory <config-directory>`: Change the config directory. The default is the current working directory.
|
|
152
|
+
- `--disable-telemetry`: Disable telemetry.
|
|
153
|
+
- `--log-level <level>`: The minimum severity of logs to show in the CLI output. Options are `debug`, `info`, `warn` or `error`. The default is `info`.
|
|
154
|
+
|
|
155
|
+
## test
|
|
156
|
+
|
|
157
|
+
The `test` command runs the app's config tests — every journey in `tests/journeys/`, sub-folders included, except folders whose name starts with `_` (such as `_candidates/`). It starts the development server headless on a free port, runs every journey through the dev server's journey route, prints `PASS`/`FAIL` per journey with the failing step, stops the server, and exits with code `1` if any journey failed. A `PASS` line shows the journey's tier, rank, rate and failures over the usage window when it has production evidence. A journey with `deprecated: true` is skipped and listed as `SKIP deprecated`. See [Config Tests](/config-tests).
|
|
158
|
+
|
|
159
|
+
- `--config-directory <config-directory>`: Change the config directory. The default is the current working directory.
|
|
160
|
+
- `--dev-directory <dev-directory>`: Change the dev directory, the directory in which the development server is placed. The default is `<config-directory>/.lowdefy/dev`.
|
|
161
|
+
- `--disable-telemetry`: Disable telemetry.
|
|
162
|
+
- `[paths...]`: Journey files, directories (read with their sub-folders) or quoted globs such as `'tests/journeys/review/**'` to run instead of the whole suite, anywhere under the config directory, candidates in `tests/journeys/_candidates/` included. A glob that matches nothing exits with code `1`.
|
|
163
|
+
- `--tag <tag>`: Only run journeys whose `tags` include this tag. Repeat it to run the journeys carrying any of the tags. Exits with code `1` if no journey matches.
|
|
164
|
+
- `--filter <name>`: Only run journeys whose `name` contains this string (case-insensitive). Repeat it to run the journeys matching any of the strings. Exits with code `1` if no journey matches.
|
|
165
|
+
- `--tier <tier>`: Only run the journeys in this popularity tier of the selection, ranked by recent production use: `common` (p50, the happy paths), `wide` (p80), `edge` (p95) or `full` (every journey, the default). Journeys with no counts for their current steps run in every tier. A tiered run never records as the suite's run. Exits with code `1` when the selection has fewer than 100 journey matches in the usage window, or no evidence. See [Usage and tiers](/config-tests#usage-and-tiers).
|
|
166
|
+
- `--usage-window <months>`: The calendar months recent use is ranked over, for `--tier` and the `PASS` line, such as `6m`. The default is `3m`.
|
|
167
|
+
- `--lint`: Check the journeys for the lint rules (L1 placeholders, L2 unasserted actions, L3 fixed waits, L4 writes without data, L5 named data set users, L6 final assertion, L7 pointless `as`) and run nothing. Exits with code `1` on any lint error. See [Lint](/config-tests#lint).
|
|
168
|
+
- `--log-level <level>`: The minimum severity of logs to show in the CLI output. Options are `debug`, `info`, `warn` or `error`. The default is `info`.
|
|
169
|
+
- `--port <port>`: The port to start the development server on. If it is in use, the next free port is used. The default is `3000`.
|
|
170
|
+
- `--ref-resolver <ref-resolver-function-path>`: Path to a JavaScript file containing a `_ref` resolver function to be used as the app default `_ref` resolver.
|
|
171
|
+
- `--repeat <n>`: Run each journey `n` times (1 to 10) and classify it `PASS`, `FLAKY` or `FAIL`. Exits with code `1` on any `FLAKY` or `FAIL`. See [Replaying candidates](/config-tests#replaying-candidates).
|
|
172
|
+
- `--url <url>`: Run the journeys against an already running development server (for example `--url http://localhost:3000` while `lowdefy dev` is running) instead of starting one.
|
|
173
|
+
|
|
174
|
+
## journeys harden
|
|
175
|
+
|
|
176
|
+
The `journeys harden` command measures whether journeys fail when the feature they walk breaks. It runs each journey once, lists the config mutants on what the runs exercised, runs each mutant against the journeys that reached it, only in their own browsers, and prints progress lines as it goes, reports every mutant no journey noticed with its source line, and a score per journey, in `.lowdefy/test/mutation.json`. It exits with code `0` even with survivors. See [Mutants](/config-tests#mutants-lowdefy-journeys-harden).
|
|
177
|
+
|
|
178
|
+
- `[paths...]`: Journey files, directories or globs to harden instead of the whole suite, as for `test`.
|
|
179
|
+
- `--filter <name>`: Only journeys whose `name` contains this string.
|
|
180
|
+
- `--page <pageId...>`: Only mutants on these pages, and endpoint mutants a journey touching them called. Journeys whose last measured run touched none of the pages are left out of the baseline too (never when there is no record for them, the journey changed, or the record was measured on a different config; the log says which). Records match by a hash of the built config, not by server start, so run `lowdefy test` after your last config edit.
|
|
181
|
+
- `--operators <list>`: Only these operators, comma separated: `drop-action`, `skip-validate`, `flip-visible`, `swap-if`, `drop-payload`, `retarget-link`, `drop-block`, `drop-step`.
|
|
182
|
+
- `--max <n>`: Run at most `n` mutants. The default is `200`; `0` means no cap.
|
|
183
|
+
- `--seed <n>`: The sample's seed; another seed draws another sample. The default is `0`.
|
|
184
|
+
- `--workers <n>`: Journey runs at once, 1 to 16. The default is `4`.
|
|
185
|
+
- `--mutant <id>`: Run only this mutant against the journeys on its path, without replacing the report.
|
|
186
|
+
- `--list`: Print the sampled mutants and a time estimate, and run nothing.
|
|
187
|
+
- `--json`: Print the report as JSON.
|
|
188
|
+
- `--url <url>`, `--port <port>`, `--config-directory`, `--dev-directory`, `--ref-resolver`, `--log-level`, `--disable-telemetry`: As for `test`.
|
|
189
|
+
|
|
190
|
+
## journeys variants
|
|
191
|
+
|
|
192
|
+
The `journeys variants` command writes edge-case candidates of one journey — other roles (`role`), another organization (`tenant`), empty and large data (`empty`, `volume`), bad input (`negative`), a reload mid-flow (`interrupt`) and a double click (`double-submit`) — to `tests/journeys/_candidates/variants/<source>/<journey>-<kind>.yaml`, and replays each three times. See [Variants](/config-tests#variants-lowdefy-journeys-variants).
|
|
193
|
+
|
|
194
|
+
- `<file>`: The journey file to vary.
|
|
195
|
+
- `--name <journey>`: The journey to vary, when the file holds several.
|
|
196
|
+
- `--kinds <list>`: Only these kinds, comma separated. The `role` and `tenant` kinds read the users and fixtures of the journey's data set.
|
|
197
|
+
- `--empty-data <name>`: The data set the `empty` variant runs on: one with no rows, and a user with the journey user's name.
|
|
198
|
+
- `--volume-data <name>`: The data set the `volume` variant runs on: one with many rows, and a user with the journey user's name.
|
|
199
|
+
- `--no-run`: Write the variants without replaying them.
|
|
200
|
+
- `--url <url>`, `--port <port>`, `--config-directory`, `--dev-directory`, `--ref-resolver`, `--log-level`, `--disable-telemetry`: As for `test`.
|
|
201
|
+
|
|
202
|
+
## journeys scope
|
|
203
|
+
|
|
204
|
+
The `journeys scope` command prints what a change touched, for a coding agent exploring a pull request: each page the change reached, why (its own config, a request, an endpoint, a connection or a websocket it uses, an app-wide artifact; changes that travel through `_ref` show on every page that refs them), the blocks added, changed or removed, and who can open the page, with the data set users under `tests/data/` it admits. It builds the merge base and the working tree in full with the installed dev server's builder and needs no running dev server; when none is installed, it installs one first without starting it. See [Exploring a pull request](/explore-pull-request).
|
|
205
|
+
|
|
206
|
+
- `--base <ref>`: Compare with the merge base of this branch or commit and `HEAD`, such as the pull request's base branch. Without it, every page of the head is listed.
|
|
207
|
+
- `--json`: Print the scope as JSON instead of the summary.
|
|
208
|
+
- `--config-directory`, `--dev-directory`, `--ref-resolver`, `--log-level`, `--disable-telemetry`: As for `test`.
|
|
209
|
+
- `--skip-plugin-checks`: Skip every plugin build check rule in both builds. As for `build`.
|
|
210
|
+
|
|
211
|
+
## journeys session
|
|
212
|
+
|
|
213
|
+
The `journeys session [<id>]` command reads the sessions the development server recorded in `.lowdefy/traces/dev/`, or, with `--source production`, the production cache [`journeys pull posthog`](#journeys-pull-posthog) writes. Without an id it lists them, newest first: the session id, its time span, the pages visited, and how many interactions it holds and how many failed. With an id it prints that session as a log, one line per interaction with what the app did in response, such as `click save → Validate failed [priority]`, to write journeys from. A production log never shows a typed value, and shows clicked text only when it is text from the app's config. An id not in the window exits with code `1`, naming the newest sessions. Agents connected to the development server read dev sessions with the `lowdefy_journey_session` tool. Set `LOWDEFY_DEV_RECORD=false` to turn dev recording off. See [Session logs](/config-tests#session-logs).
|
|
214
|
+
|
|
215
|
+
- `--source <source>`: `dev` (the default) or `production`.
|
|
216
|
+
- `--since <since>`: Dev: only sessions with records at or after this time, a duration back from now (`30m`, `2h`, `7d`) or an ISO date. Production: the window ending today, a number of days such as `30d` (the default) or a start date, at most 30 days.
|
|
217
|
+
- `--from <YYYY-MM-DD>`, `--to <YYYY-MM-DD>`: Production only. An explicit window of whole UTC days instead of `--since`.
|
|
218
|
+
- `--json`: Print the list or the log as JSON on stdout.
|
|
219
|
+
- `--config-directory <config-directory>`: Change the config directory. The default is the current working directory.
|
|
220
|
+
- `--dev-directory <dev-directory>`: Change the dev directory, where the development server's build is read from. The default is `<config-directory>/.lowdefy/dev`.
|
|
221
|
+
- `--disable-telemetry`: Disable telemetry.
|
|
222
|
+
- `--log-level <level>`: The minimum severity of logs to show in the CLI output. Options are `debug`, `info`, `warn` or `error`. The default is `info`.
|
|
223
|
+
|
|
224
|
+
## journeys pull posthog
|
|
225
|
+
|
|
226
|
+
The `journeys pull posthog` command reads the app's production analytics from its PostHog project, one UTC day at a time, and writes them as interaction traces to `.lowdefy/traces/production/<YYYY-MM-DD>.jsonl`, with a `<YYYY-MM-DD>.manifest.json` beside each day. `journeys session`, `journeys evidence` and `journeys coverage` read that cache with `--source production`. See [Production journeys](/config-tests#production-journeys).
|
|
227
|
+
|
|
228
|
+
It reads three environment variables (the app's `.env` file is loaded first):
|
|
229
|
+
|
|
230
|
+
- `POSTHOG_PROJECT_ID`: The PostHog project the app sends its analytics to.
|
|
231
|
+
- `POSTHOG_API_HOST`: The project's API host, an `https://` URL such as `https://eu.posthog.com`. There is no default, because the wrong region answers as if the key were wrong.
|
|
232
|
+
- `POSTHOG_PERSONAL_API_KEY`: Your own PostHog personal API key, scoped to the project with the **Query Read** scope. Export it in your shell or put it in the app's `.env`; never commit it. It is sent only to `POSTHOG_API_HOST` and never logged or written to a manifest.
|
|
233
|
+
|
|
234
|
+
A day older than yesterday is final: it is pulled once and skipped afterwards. Today and yesterday are pulled again on every run, because PostHog accepts late events. Day files older than 400 days are removed at the start of each pull. Person and organisation ids are hashed with a random salt kept in `.lowdefy/traces/production/salt`, which never leaves your machine. Only the pull creates the salt. `journeys session`, `journeys coverage` and `journeys evidence` read a day only when it was pulled under this salt: a day pulled under another one (the salt file deleted, or the cache copied from another machine) reads as missing, with the pull that fetches it again.
|
|
235
|
+
|
|
236
|
+
Clicked text is never written. Each clicked element's text is stored as a token, a hash under the same salt, so clicks on the same text can be grouped and counted without it. `journeys session`, `journeys coverage` and `journeys evidence` turn a token back into text only when it is the hash of a string in the app's config: the built pages, menus, i18n messages, block plugins' default messages and antd's locale strings for the app's locales. They collect those strings with one full build of the app by the installed development server (run `lowdefy dev` once first), cached until the config changes. Any other text, such as a customer's name in a grid cell or a label built from values, stays a token.
|
|
237
|
+
|
|
238
|
+
Pull, session and coverage read at most 30 UTC days at a time, and refuse a longer window; `journeys evidence` is not capped. The first pull or production read after upgrading from a version that stored clicked text deletes the day files pulled that way, any `tests/journeys/_candidates/production/` an earlier version wrote, and `.lowdefy/test/coverage.json`, which the next pull and coverage write again. Committed journeys are never changed.
|
|
239
|
+
|
|
240
|
+
- `--since <since>`: The days to pull, ending today: a number of days such as `30d`, or a start date. The default is `30d`, and the longest window is 30 days.
|
|
241
|
+
- `--from <YYYY-MM-DD>`, `--to <YYYY-MM-DD>`: An explicit window of whole UTC days instead of `--since`, at most 30 days. Pass both.
|
|
242
|
+
- `--environment <name>`: Only events whose `environment` super property is this, for a project that receives several environments. By default nothing is filtered.
|
|
243
|
+
- `--include-test-accounts`: Include the events the project's test-account filter leaves out.
|
|
244
|
+
- `--org-property <name>`: The person property holding the organisation id. The default is `org_id`.
|
|
245
|
+
- `--roles-property <name>`: The person property holding the roles. The default is `roles`.
|
|
246
|
+
- `--page-size <rows>`: Rows read per query, at most `50000`. The default is `10000`.
|
|
247
|
+
- `--max-rows <rows>`: Stop before the pull would read more rows than this, and say to shorten `--since`. The default is `500000`.
|
|
248
|
+
- `--refetch`: Pull final days again.
|
|
249
|
+
- `--config-directory <config-directory>`: Change the config directory. The default is the current working directory.
|
|
250
|
+
- `--disable-telemetry`: Disable telemetry.
|
|
251
|
+
- `--log-level <level>`: The minimum severity of logs to show in the CLI output. Options are `debug`, `info`, `warn` or `error`. The default is `info`.
|
|
252
|
+
|
|
253
|
+
When PostHog rate limits the pull for longer than a minute, or the project's hourly query budget for personal keys runs out, the pull stops, keeps the days it has written, and says when to run it again. The next run picks up where it stopped.
|
|
254
|
+
|
|
255
|
+
## journeys evidence
|
|
256
|
+
|
|
257
|
+
The `journeys evidence` command works out how much production use backs each journey in `tests/journeys/`, by calendar month: the sessions that did what the journey does, the people and organisations behind them, and how many of them failed. It reads every final day of the production cache (today and yesterday are not final until a later pull), not a window, and gaps in the cache are fine. A month already counted from at least as many final days is not read again, so a routine refresh reads the current month. Days pulled with different filters (project, environment, test accounts) are refused. See [Evidence](/config-tests#evidence).
|
|
258
|
+
|
|
259
|
+
A journey's click text counts only when it is text from the app's config, as production text is read: a journey clicking a grid cell by a customer's name is backed exactly as one clicking it with no text, so no command confirms whether production showed a value.
|
|
260
|
+
|
|
261
|
+
Without `--refresh` it prints what would change and writes nothing. With `--refresh` it rewrites the `evidence` key of each journey whose numbers changed, and nothing else in the file. It is the only command that writes `evidence`. When a journey's steps change what it matches in production, its counted months move to a deprecated flow that is still counted, and the new flow is counted from the cache. Afterwards it lists the journeys no production session backs over the last 3 months, beside their mutation numbers. It never removes a journey.
|
|
262
|
+
|
|
263
|
+
- `--refresh`: Write the changed `evidence` keys.
|
|
264
|
+
- `--source <source>`: Where use is read from. Only `production` for now, the default.
|
|
265
|
+
- `--config-directory`, `--dev-directory`, `--disable-telemetry`, `--log-level`: As for [`journeys session`](#journeys-session).
|
|
266
|
+
|
|
267
|
+
## journeys usage
|
|
268
|
+
|
|
269
|
+
The `journeys usage` command reports which journeys real use leans on most. It ranks the journeys in `tests/journeys/` by their recent rate: their production sessions over the final days their months hold in the usage window, the last 3 calendar months ending at the newest month any selected journey has. Each journey shows its popularity tier, its sessions and failures over the window and all time, a line per month with that month's persons and organisations, and its deprecated flows with their recent use. Below that it lists the production flows no journey covers, from the report [`journeys coverage`](#journeys-coverage) writes, ranked by their sessions in coverage's window and not tiered, when coverage grouped them into flows; otherwise it says why it lists none. See [Usage and tiers](/config-tests#usage-and-tiers).
|
|
270
|
+
|
|
271
|
+
A tier is a cut through the selected journeys, ranked by rate, most first: `common` holds the shortest run of journeys reaching 50% of the summed rates, `wide` 80% and `edge` 95%, and `full` holds every journey. Tiers nest and never split journeys with equal rates. A journey edited since the last refresh, or never refreshed, is `unranked` and in every tier. A journey with `deprecated: true` is in no tier. Fewer than 100 journey matches in the window refuses every tier but `full`.
|
|
272
|
+
|
|
273
|
+
- `[paths...]`, `--filter <name>`, `--tag <tag>`: The journeys to report on, selected as [`test`](#test) selects them. Tiers are cut over this selection alone.
|
|
274
|
+
- `--tier <tier>`: Only the journeys in `common`, `wide`, `edge` or `full` (the default, every journey).
|
|
275
|
+
- `--usage-window <months>`: The calendar months recent use is ranked over, such as `3m`, the default.
|
|
276
|
+
- `--json`: Print the report as JSON, for agents.
|
|
277
|
+
- `--config-directory`, `--dev-directory`, `--disable-telemetry`, `--log-level`: As for [`journeys session`](#journeys-session).
|
|
278
|
+
|
|
279
|
+
## journeys coverage
|
|
280
|
+
|
|
281
|
+
The `journeys coverage` command reports what real use no journey in `tests/journeys/` covers yet, five ways, each with its uncovered items ranked by use, and writes the report with the production profile to `.lowdefy/test/coverage.json`. A journey's click text counts only when it is text from the app's config; any other text in a journey reads as no text, so the click matches that block and column's clicks. A journey with `deprecated: true` is never run, so it covers nothing and is left out. When the development server recorded a full test run, the interaction measure adds the share that run drove, and failure coverage counts only failures a passing journey produced. The flow measure groups sessions into flows only when the window holds 100,000 rows or more; below that it is left out, the summary says why and points to [`journeys session --source production`](#journeys-session), and the report's `flowGrouping` records it. See [Coverage](/config-tests#coverage).
|
|
282
|
+
|
|
283
|
+
- `--group`: Group sessions into flows whatever the window holds.
|
|
284
|
+
- `--no-group`: Never group sessions into flows.
|
|
285
|
+
- `--json`: Print the report as JSON instead of the summary.
|
|
286
|
+
- `--source <source>`: Where use is read from. Only `production` for now, the default.
|
|
287
|
+
- `--since <since>`, `--from <YYYY-MM-DD>`, `--to <YYYY-MM-DD>`: The production window, as for [`journeys pull posthog`](#journeys-pull-posthog), at most 30 days.
|
|
288
|
+
- `--config-directory`, `--dev-directory`, `--disable-telemetry`, `--log-level`: As for [`journeys session`](#journeys-session).
|
|
289
|
+
|
|
290
|
+
## upgrade
|
|
291
|
+
|
|
292
|
+
The `upgrade` command upgrades a Lowdefy app to a newer version by walking you through migration prompts that handle breaking changes.
|
|
293
|
+
|
|
294
|
+
It fetches the latest `@lowdefy/codemods` package, resolves the version chain from your current version to the target, and presents migration prompts phase by phase.
|
|
295
|
+
|
|
296
|
+
```
|
|
297
|
+
pnpx lowdefy@5 upgrade
|
|
298
|
+
pnpx lowdefy@5 upgrade --to 6.0.0
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
- `--to <version>`: Target version to upgrade to. Defaults to the latest stable release.
|
|
302
|
+
- `--plan`: Show the upgrade plan without executing.
|
|
303
|
+
- `--resume`: Resume a previously interrupted upgrade.
|
|
304
|
+
- `--config-directory <config-directory>`: Change the config directory. The default is the current working directory.
|
|
305
|
+
- `--log-level <level>`: The minimum severity of logs to show in the CLI output. Options are `debug`, `info`, `warn` or `error`. The default is `info`.
|
|
306
|
+
|
|
307
|
+
### How it works
|
|
308
|
+
|
|
309
|
+
1. Reads your current version from `lowdefy.yaml`.
|
|
310
|
+
2. Queries npm for the latest stable Lowdefy version (or uses `--to`).
|
|
311
|
+
3. Fetches `@lowdefy/codemods@latest` — the codemods package containing all migration prompts.
|
|
312
|
+
4. Resolves the upgrade chain — which intermediate versions need codemods.
|
|
313
|
+
5. Presents migration prompts phase by phase. Each prompt can be copied to clipboard for use with any AI coding tool, viewed as a manual guide, or skipped for later.
|
|
314
|
+
6. Updates `lowdefy.yaml` after each phase and suggests a git commit.
|
|
315
|
+
|
|
316
|
+
See the [Upgrade Guide](/upgrade-guide) for more detail on how the upgrade system works.
|
|
317
|
+
|
|
318
|
+
## start
|
|
319
|
+
|
|
320
|
+
The `start` command starts a Lowdefy production server. To start a Lowdefy server, tha app should first be built using the `build` command.
|
|
321
|
+
|
|
322
|
+
- `--config-directory <config-directory>`: Change the config directory. The default is the current working directory.
|
|
323
|
+
- `--disable-telemetry`: Disable telemetry.
|
|
324
|
+
- `--exit-with-pid <pid>`: Stop the server when the process with this id exits. For test runners and scripts that start the server. The `LOWDEFY_EXIT_WITH_PID` environment variable does the same, and passes through wrappers such as `pnpm exec` or a secrets manager.
|
|
325
|
+
- `--log-level <level>`: The minimum severity of logs to show in the CLI output. Options are `debug`, `info`, `warn` or `error`. The default is `info`.
|
|
326
|
+
- `--port <port>`: Change the port the server is hosted at. The default is `3000`.
|
|
327
|
+
- `--server-directory <server-directory>`: Change the server directory, the directory in which the production server is placed. The default is `<config-directory>/.lowdefy/server`.
|
|
328
|
+
|
|
329
|
+
The server stops when the `lowdefy start` process stops, however it stops, including when it is killed outright. A server run directly with `node`, as in a Docker image, is not affected.
|
|
330
|
+
|
|
331
|
+
|
|
332
|
+
#### Examples
|
|
333
|
+
|
|
334
|
+
|
|
335
|
+
Run the dev server, watching a relative directory for file changes:
|
|
336
|
+
```txt
|
|
337
|
+
pnpx lowdefy@5 dev --watch ../other-project
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
Run the dev server, ignoring the public directory:
|
|
341
|
+
```txt
|
|
342
|
+
pnpx lowdefy@5 dev --watch-ignore public/**
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
|
|
346
|
+
|
|
347
|
+
# Module Fetching
|
|
348
|
+
|
|
349
|
+
When your app uses [modules](/modules), the build automatically fetches module sources during the build phase. GitHub modules are downloaded as tarballs and cached in `.lowdefy/modules/`. Multiple module entries from the same monorepo share a single cache entry. Local `file:` sources are read directly from disk.
|
|
350
|
+
|
|
351
|
+
For private GitHub repositories, set the `GITHUB_TOKEN` environment variable:
|
|
352
|
+
|
|
353
|
+
```
|
|
354
|
+
GITHUB_TOKEN=ghp_your_token_here
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
Without `GITHUB_TOKEN`, the CLI uses the token of the `gh` CLI when one is signed in.
|
|
358
|
+
|
|
359
|
+
To read a private repository with an SSH key, such as a read-only deploy key, set `GITHUB_SSH_KEY` to the private key. When the GitHub API cannot find a repository or refuses the token, the build fetches it with `git` over SSH using that key. See [modules](/modules) for details.
|
|
360
|
+
|
|
361
|
+
In development mode (`lowdefy dev`), local module sources (`file:` paths) are watched for changes and trigger rebuilds automatically.
|
|
362
|
+
|
|
363
|
+
# Configuration
|
|
364
|
+
|
|
365
|
+
All the CLI options can either be set as command line options, or the `cli` config object in your `lowdefy.yaml` file. Options set as command line options take precedence over options set in the `lowdefy.yaml` file. The config in the `lowdefy.yaml` cannot be referenced using the `_ref` operator, but need to be set in the file itself.
|
|
366
|
+
|
|
367
|
+
Options set in the `lowdefy.yaml` should be defined in camelCase. The options that can be set are:
|
|
368
|
+
- `devDirectory: string`: Change the dev directory, the directory in which the development server is placed. The default is `<config-directory>/.lowdefy/dev`.
|
|
369
|
+
- `devScript: string`: The `package.json` script the [hub](#hub) runs to start this app's dev server for coding agents. Required when several scripts run `lowdefy dev`.
|
|
370
|
+
- `disableTelemetry: boolean`: Disable telemetry.
|
|
371
|
+
- `logLevel: enum`: The minimum severity of logs to show in the CLI output. Options are `debug`, `info`, `warn` or `error`. The default is `info`.
|
|
372
|
+
- `noOpen`: Do not open a new tab in the default browser.
|
|
373
|
+
- `port: number`: Change the port the server is hosted at. The default is `3000`.
|
|
374
|
+
- `refResolver: string`: Path to a JavaScript file containing a `_ref` resolver function to be used as the app default `_ref` resolver.
|
|
375
|
+
- `serverDirectory: string`: Change the server directory, the directory in which the production server is placed. The default is `<config-directory>/.lowdefy/server`.
|
|
376
|
+
- `watch: string[]`: A list of paths to files or directories that should be watched for changes.
|
|
377
|
+
- `watchIgnore: string[]`: A list of paths to files or directories that should be ignored by the file watcher. Globs are supported.
|
|
378
|
+
- `skipCodemodCheck: boolean`: Suppress warnings about pending codemod upgrades during build and dev.
|
|
379
|
+
|
|
380
|
+
The `--config-directory` option cannot be set from the `lowdefy.yaml` file.
|
|
381
|
+
|
|
382
|
+
# Telemetry
|
|
383
|
+
|
|
384
|
+
The CLI collects usage and error information to help us fix bugs, prioritize features, and understand how Lowdefy is being used.
|
|
385
|
+
|
|
386
|
+
All telemetry can be disabled by setting the `disableTelemetry` flag in `cli` config object in your `lowdefy.yaml` file (this cannot be a reference to another file), or by using the `--disable-telemetry` command line flag.:
|
|
387
|
+
|
|
388
|
+
###### `lowdefy.yaml`
|
|
389
|
+
```yaml
|
|
390
|
+
lowdefy: LOWDEFY_VERSION
|
|
391
|
+
|
|
392
|
+
cli:
|
|
393
|
+
disableTelemetry: true
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
We collect the following information:
|
|
397
|
+
|
|
398
|
+
- The CLI version.
|
|
399
|
+
- The Lowdefy version of your app.
|
|
400
|
+
- A random local app id (stored locally in your project folder at `.lowdefy/cli.json`).
|
|
401
|
+
- The CLI command used.
|
|
402
|
+
- Your IP address.
|
|
403
|
+
- Error messages and stack traces for any errors.
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Connections
|
|
2
|
+
|
|
3
|
+
Connections integrate your app with databases, APIs, and services; requests execute against them server-side. All 19 connections, grouped by type. See [Connections and Requests](/connections-and-requests) for the model.
|
|
4
|
+
|
|
5
|
+
SQL
|
|
6
|
+
|
|
7
|
+
Relational databases.
|
|
8
|
+
|
|
9
|
+
NoSQL & search
|
|
10
|
+
|
|
11
|
+
Document stores, search, and caching.
|
|
12
|
+
|
|
13
|
+
AI
|
|
14
|
+
|
|
15
|
+
LLM providers and MCP tools.
|
|
16
|
+
|
|
17
|
+
Storage & sheets
|
|
18
|
+
|
|
19
|
+
Object storage and spreadsheets.
|
|
20
|
+
|
|
21
|
+
HTTP & services
|
|
22
|
+
|
|
23
|
+
HTTP APIs and hosted services.
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# Operators
|
|
2
|
+
|
|
3
|
+
Operators are functions written directly in config — they evaluate wherever they appear. All 70 operators, grouped by what they do. See [Operators](/operators) for how evaluation works.
|
|
4
|
+
|
|
5
|
+
Logic & control
|
|
6
|
+
|
|
7
|
+
Branch, compare, and combine conditions.
|
|
8
|
+
|
|
9
|
+
State & context
|
|
10
|
+
|
|
11
|
+
Read page, user, and app context.
|
|
12
|
+
|
|
13
|
+
Requests & APIs
|
|
14
|
+
|
|
15
|
+
Read request responses and API results.
|
|
16
|
+
|
|
17
|
+
Build & config
|
|
18
|
+
|
|
19
|
+
Compose config at build time.
|
|
20
|
+
|
|
21
|
+
App & i18n
|
|
22
|
+
|
|
23
|
+
App metadata, menus, theme, and translations.
|
|
24
|
+
|
|
25
|
+
Data manipulation
|
|
26
|
+
|
|
27
|
+
Get, shape, and query data structures.
|
|
28
|
+
|
|
29
|
+
Math
|
|
30
|
+
|
|
31
|
+
Arithmetic and number utilities.
|
|
32
|
+
|
|
33
|
+
String
|
|
34
|
+
|
|
35
|
+
Transform and match strings.
|
|
36
|
+
|
|
37
|
+
Date & time
|
|
38
|
+
|
|
39
|
+
Create and format dates.
|
|
40
|
+
|
|
41
|
+
Programming
|
|
42
|
+
|
|
43
|
+
Escape hatches into JavaScript and expressions.
|
|
44
|
+
|
|
45
|
+
Format & encode
|
|
46
|
+
|
|
47
|
+
Serialize, encode, and hash values.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Reference
|
|
2
|
+
|
|
3
|
+
Every Lowdefy primitive, by the book. New to Lowdefy? Start with
|
|
4
|
+
[The Four Primitives](/four-primitives) under Learn.
|
|
5
|
+
|
|
6
|
+
114 UI components — inputs, tables, charts, containers, and lists.
|
|
7
|
+
|
|
8
|
+
70 functions that express logic and shape data anywhere in config.
|
|
9
|
+
|
|
10
|
+
24 event handlers that make pages interactive.
|
|
11
|
+
|
|
12
|
+
19 integrations — databases, storage, HTTP services, and AI providers.
|
|
13
|
+
|
|
14
|
+
Flow control for API routines — loops, branches, and error handling.
|
|
15
|
+
|
|
16
|
+
The shape of app, page, block, request, and auth config.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# Schema Reference
|
|
2
|
+
|
|
3
|
+
Every Lowdefy app is one config object, assembled from your YAML files at build time.
|
|
4
|
+
The schema material lives with the concept that owns it — this hub points to each area.
|
|
5
|
+
|
|
6
|
+
The lowdefy.yaml root object, pages, and how config is assembled.
|
|
7
|
+
|
|
8
|
+
The block object — id, type, properties, layout, style, events, and slots.
|
|
9
|
+
|
|
10
|
+
Connections, requests, and payloads.
|
|
11
|
+
|
|
12
|
+
Providers, adapters, callbacks, and protected pages.
|