FluidDocs

Getting Started CLI

fld is the FluidDocs command-line client. Use it to sign in, create and edit docs, publish, run builder AI jobs, and inspect analytics — with short Linux-style commands that work well for humans and coding agents.

Binary name: fld. Run fld --help for workflows, flags, and examples in one place. Default output is human-readable; pass --json for machine-readable JSON.

Install

Install the CLI with a one-liner (detects your OS and architecture):

curl -fsSL https://fluiddocs.ai/install | bash

Verify:

fld --help

Ensure ~/.local/bin is on your PATH. For a local server, set FLUIDDOCS_INSTALL_BASE=http://localhost:8080 before piping the script, or download the matching binary from /install/fld-*.

Authenticate

fld login

This opens a browser window where you authorize access. Credentials are cached in ~/.config/fluiddocs/auth.json. Then verify with:

fld whoami
fld status
fld logout

Host & token

Point at another server with FLUIDDOCS_URL, or override the cached token:

export FLUIDDOCS_URL=http://localhost:8080
fld --token lit_live_… whoami
fld --json whoami

Common workflows

Commands are flat (no nested groups). Default output is a short human-readable summary; add --json for scripts and agents.

Deploy HTML

fld create --name "Hello" --zip ./index.html
fld upload --file ./index.html --name "Hello"
fld redeploy --project-id PROJECT_ID --zip ./index.html

List & filter

ls is non-recursive by default (root-level projects only when flat). Use -R / --rec to include nested folders; filter with --name and --folder-id.

fld ls
fld ls --name demo
fld ls --name "My Doc" --name-match exact
fld ls --folder-id FOLDER_ID
fld ls -R                                   # all nested projects
fld ls --folder-id FOLDER_ID -R
fld --json ls

Edit drafts

fld write PROJECT_ID --file ./index.html --autocommit
fld cat PROJECT_ID
fld stat PROJECT_ID
fld patch PROJECT_ID --path index.html --find "Old" --replace "New"
fld commit PROJECT_ID

Publish

fld publish PROJECT_ID --slug my-doc
fld vis public PROJECT_ID

Builder chat & Ask AI

# Enable Ask AI on a published doc
fld enable-chat PROJECT_ID

# Ground answers in the doc (auto-indexes; waits by default)
fld enable-chat PROJECT_ID --grounded

# Grounded, but index another project's files as the knowledge source
fld enable-chat PROJECT_ID --grounded --source-project-id OTHER_ID

# Turn Ask AI off
fld enable-chat PROJECT_ID --disable

# Builder AI edit
fld chat --message "Add a pricing table" --project-id PROJECT_ID --wait
fld deck-build --description "Seed-stage pitch for Acme" --deck-type pitch --wait
fld agent-task --prompt "Return {title, h1Text} as JSON" --project-id PROJECT_ID --read-only --wait
fld --json chat --message "…" --project-id PROJECT_ID --wait

Commands

Full help: fld --help. Older names in parentheses remain as aliases.

Docs

Command	What it does
`fld whoami` (`me`)	Show the signed-in user and org
`fld ls` (`list`)	List docs. Filter with `--name` / `--folder-id`; add `-R` for nested folders
`fld stat ID` (`get`)	Show project metadata (name, slug, visibility, …)
`fld cat ID`	Print the draft HTML (default path `index.html`)
`fld patch ID`	Update project settings (`--body` JSON) or find/replace text in a file
`fld cp ID` (`copy`)	Duplicate a project (optional `--name`, `--prompt`)
`fld publish ID --slug`	Publish under a public URL slug
`fld vis MODE ID` (`visibility`)	Set who can open it: `public`, `unlisted`, or `private`
`fld templates`	List templates available in your org

Deploy

Command	What it does
`fld create --zip\|--dir`	Create a new doc from a zip, HTML file, or directory
`fld redeploy --project-id`	Replace the files in an existing project
`fld upload --file`	Upload a single file as a new doc (or into `--project-id`)

Draft & files

Command	What it does
`fld write ID --file`	Write draft HTML from a file or `--content`; add `--autocommit` to go live
`fld commit ID`	Promote the current draft to the live version
`fld lines ID --patch`	Apply a line-based patch to the draft
`fld append ID`	Append text to a file inside the project
`fld apply ID --body`	Apply a batch of structured ops from JSON

Jobs & AI

AI commands start a background job and return a job id. Add --wait to stream the bot’s progress to your terminal and block until it finishes, or run fld poll JOB_ID later.

Command	What it does
`fld enable-chat ID`	Enable Ask AI on a published doc. Add `--grounded` to ground answers and auto-index; `--source-project-id` to index another doc; `--disable` to turn off
`fld chat`	Talk to the builder AI. Omit `--project-id` to create a new doc. Use `--visitor` for Ask AI on a published doc (no login)
`fld deck-build`	Generate a deck from a description and deck type (pitch, sales, …)
`fld agent-task`	Run a one-shot agent task on a project (optional `--read-only`)
`fld viewer-index`	Build the Ask-AI search index for a published doc
`fld result` / `fld poll`	Fetch a finished result, or wait (and stream output) until the job completes

Analytics

fld track records events and needs no login. Query commands use your cached token (or --token).

Command	What it does
`fld track ID --event-type … [--sub-type] [--extra]`	Record a visit, CTA click, or custom event (no login)
`fld analytics visits ID`	Visit counts and aggregates for a project
`fld analytics events ID --event-type …`	Query activity events (requires a filter such as `--event-type`)
`fld analytics visitors ID`	Recent unique visitors
`fld analytics chats ID`	List Ask-AI chats on a published doc
`fld analytics chat JOB_ID`	Full transcript for one Ask-AI chat

# Push a CTA click (no login)
fld track PROJECT_ID --event-type cta_click --sub-type "Book a demo" \
  --extra '{"href":"https://cal.example/demo"}'

# Query those events (login required; needs a filter)
fld analytics events PROJECT_ID --event-type cta_click --limit 20

# Visit aggregates + recent visitors + viewer Ask-AI chats
fld analytics visits PROJECT_ID
fld analytics visitors PROJECT_ID
fld analytics chats PROJECT_ID
fld analytics chat JOB_ID

Agent tips

Always pass --json for machine-readable stdout (errors included).
JSON bodies: --body '{"…"}' or --body @payload.json.
File contents: --file path or --content @path.
Long-running jobs: add --wait to stream bot output, or poll with fld poll JOB_ID.
Set FLUIDDOCS_PROJECT_ID to avoid repeating --project-id.
fld ls defaults to non-recursive; agents that need the full tree should pass -R.
Viewer chat: fld chat --visitor --project-id ID --message "…" (no login; doc must be published).
Analytics: fld track to record (no login); fld analytics events|visits|visitors|chats to query.

Prefer the HTTP API? See the REST API guide. Building in-page widgets? See the UI SDK.