103 lines
4 KiB
Markdown
103 lines
4 KiB
Markdown
|
---
|
||
|
|
name: bliss
|
||
|
|
description: Drive a remote Bliss instance from the command line the way a human uses the /workshop UI — create/edit structures, routes, templates, databases, run the db REPL, read logs. Use when asked to build, inspect, or modify Bliss Structures against a running instance.
|
||
|
|
---
|
||
|
|
|
||
|
|
# bliss CLI
|
||
|
|
|
||
|
|
`bliss` talks to a running Bliss instance exactly as a human does through the
|
||
|
|
workshop UI. **Reads** come back as JSON from the `/plumbing` API (pipe into
|
||
|
|
`jq`). **Writes** go through the same `/workshop/*` endpoints the UI posts to.
|
||
|
|
|
||
|
|
## Setup
|
||
|
|
|
||
|
|
The CLI is at `bliss-cli/bliss` in the repo. Configure via env vars:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
export BLISS_URL=https://your-instance.example.com # default http://localhost:3000
|
||
|
|
export BLISS_USER=you
|
||
|
|
export BLISS_PASS=secret
|
||
|
|
```
|
||
|
|
|
||
|
|
It logs in once and caches the session cookie under `~/.bliss/`, re-logging-in
|
||
|
|
automatically when it expires. Run it as `node bliss-cli/bliss <command>` (or
|
||
|
|
`./bliss-cli/bliss` if on PATH).
|
||
|
|
|
||
|
|
## The model (what you're editing)
|
||
|
|
|
||
|
|
A **Structure** is a mini web app. It has **routes** (a VERB + path + a JS
|
||
|
|
`handler` string run in a sandbox), **templates** (Eta, with a `test_object`
|
||
|
|
used for preview), and **databases** (each with a `library` JS module and its
|
||
|
|
own SQLite file). Ids are integers. Build a structure by: create it → add a db →
|
||
|
|
write its library → add routes whose handlers call the library → add templates
|
||
|
|
the handlers render.
|
||
|
|
|
||
|
|
## Reads (JSON)
|
||
|
|
|
||
|
|
```bash
|
||
|
|
bliss structures # list all structures
|
||
|
|
bliss structure <sid> # structure + its routes, templates, dbs, files
|
||
|
|
bliss route <sid> <rid> # one route incl. its handler source
|
||
|
|
bliss template <sid> <tid> # one template incl. content + test_object
|
||
|
|
bliss db <sid> <dbid> # one db incl. its library source
|
||
|
|
bliss files <sid> # files attached to a structure
|
||
|
|
bliss logs <sid> <rid> [--since <id>] # route logs (console.log output + errors)
|
||
|
|
```
|
||
|
|
|
||
|
|
All emit JSON, so: `bliss structure 3 | jq '.routes[].path'`.
|
||
|
|
|
||
|
|
## Writes
|
||
|
|
|
||
|
|
```bash
|
||
|
|
bliss create-structure "<name>" # -> {location, id}
|
||
|
|
bliss clone <sid> --name "<n>" --prefix /p [--clone-dbs]
|
||
|
|
|
||
|
|
bliss create-route <sid> <VERB> <path> # VERB: GET|POST|PUT|DELETE|WS ; -> {id}
|
||
|
|
bliss update-route <sid> <rid> --handler-file <f|-> # replace handler code
|
||
|
|
[--scaffold-file <f>] [--path <p>] [--verb <v>]
|
||
|
|
|
||
|
|
bliss create-template <sid> "<name>" # -> {id}
|
||
|
|
bliss update-template <sid> <tid> --content-file <f|-> [--test-object-file <f>]
|
||
|
|
|
||
|
|
bliss create-db <sid> "<name>" # -> {id}
|
||
|
|
bliss attach-db <sid> <dbid> <alias> # share an existing db under an alias
|
||
|
|
bliss update-library <sid> <dbid> --file <f|-> # returns eval output/errors
|
||
|
|
|
||
|
|
bliss repl <sid> <dbid> '<code>' # run JS/SQL against the db; --file <f|-> also works
|
||
|
|
bliss upload <sid> <path> # upload a static file
|
||
|
|
```
|
||
|
|
|
||
|
|
## Previews
|
||
|
|
|
||
|
|
```bash
|
||
|
|
bliss preview-route <sid> <rid> # rendered HTML of a GET route
|
||
|
|
bliss preview-template <sid> <tid> # rendered HTML using the template's test_object
|
||
|
|
```
|
||
|
|
|
||
|
|
## Editing code (handlers, templates, library)
|
||
|
|
|
||
|
|
Handlers/templates/library are multiline code. Write the code to a temp file and
|
||
|
|
pass `--*-file`, or pipe via `-` (stdin):
|
||
|
|
|
||
|
|
```bash
|
||
|
|
cat > /tmp/handler.js <<'EOF'
|
||
|
|
function handler(req, res) {
|
||
|
|
const { library } = require('db')('main');
|
||
|
|
res.render('home', { items: library.all() });
|
||
|
|
}
|
||
|
|
EOF
|
||
|
|
bliss update-route 3 12 --handler-file /tmp/handler.js
|
||
|
|
|
||
|
|
echo "function handler(req,res){ res.send('hi') }" | bliss update-route 3 12 --handler-file -
|
||
|
|
```
|
||
|
|
|
||
|
|
The db `library` runs with `sql` (the better-sqlite3 instance) in scope and sets
|
||
|
|
`module.exports`. Test it fast with `bliss repl <sid> <dbid> 'library.someFn()'`.
|
||
|
|
|
||
|
|
## Typical loop
|
||
|
|
|
||
|
|
1. `bliss structures` / `bliss structure <sid>` to orient.
|
||
|
|
2. Edit a handler/template/library into a temp file, push with the matching
|
||
|
|
`update-*` command.
|
||
|
|
3. `bliss preview-route` / `bliss repl` to see the result; `bliss logs` to debug.
|