bliss/bliss-cli/SKILL.md

name	description
bliss	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:

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)

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

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

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):

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.