ThinkFlyFlow CLI

A command-line interface for ThinkFlyFlow, built for both people and agents. Wrap the REST API into structured commands with human-friendly tables and machine-readable JSON.

Installation

The CLI is a Python package (cli-anything-thinkflyflow) installed with pip or pipx. Python 3.8+ is required.

pipx (recommended)

pipx install cli-anything-thinkflyflow

pip

pip install cli-anything-thinkflyflow

# From source (development)
git clone https://github.com/rilwan2003/thinkflyflow-cli
cd thinkflyflow-cli && pip install -e .

Verify the install:

verify

cli-anything-thinkflyflow --version
# => cli-anything-thinkflyflow, version 0.2.0

Authentication

Two credential types are supported. For headless and agent use, a Personal Access Token (PAT) is recommended because it does not expire.

Option A — Personal Access Token (recommended)

# 1) Log in once to mint a PAT
cli-anything-thinkflyflow auth login --email you@example.com --password '••••••'

# 2) Generate a non-expiring PAT (prefix "lj-")
cli-anything-thinkflyflow pat generate --name "ci-agent"

# 3) Use it via env var (never committed)
export THINKFLYFLOW_TOKEN="lj-xxxxxxxxxxxxxxxx"

Option B — Email/password (interactive)

cli-anything-thinkflyflow auth login --email you@example.com --password '••••••'

# Session state is saved; subsequent commands reuse it:
cli-anything-thinkflyflow auth me

All authenticated requests send Authorization: Bearer <token>. Access tokens last 72 hours; refresh tokens 30 days (rotated on refresh).

Configuration & profiles

Configure once and forget. The CLI reads a config file plus environment variables, so agents and CI can run without interactive login.

config file (~/.config/thinkflyflow/config.toml)

[default]
api_url   = "https://api.laureljar.com/api/v2"
profile   = "prod"

[profiles.prod]
api_url   = "https://api.laureljar.com/api/v2"
workspace = "1f78666c-0dce-470d-9d42-1796c3a6c57c"

[profiles.test]
api_url   = "https://apitest.laureljar.com/api/v2"
workspace = "<test-workspace-id>"

manage config

cli-anything-thinkflyflow config set api_url https://apitest.laureljar.com/api/v2
cli-anything-thinkflyflow config set profile test
cli-anything-thinkflyflow config list

# choose a profile per command
cli-anything-thinkflyflow --profile test workspace list

environment variables

THINKFLYFLOW_API_URL   # override the base URL
THINKFLYFLOW_TOKEN      # PAT or access token
THINKFLYFLOW_WORKSPACE  # default workspace id
THINKFLYFLOW_PROFILE    # active profile name

shell completion

# bash
eval "$(cli-anything-thinkflyflow completion bash)"
# zsh
cli-anything-thinkflyflow completion zsh > "_thinkflyflow"   # place in a dir on $fpath
# fish
cli-anything-thinkflyflow completion fish | source

Command reference

Global flags apply to every command: --json (machine output), --table (human, default), --quiet, --dry-run, --api-url, --profile, --page, --page-size, --all.

auth

Command	Description
`auth login`	Log in with email + password; stores session state
`auth signup`	Create an account
`auth me`	Show the current user
`auth refresh`	Refresh the access token

pat

Command	Description
`pat generate --name NAME`	Mint a non-expiring Personal Access Token
`pat list`	List your PATs
`pat revoke <id>`	Revoke a PAT

workspace

Command	Description
`workspace list`	List workspaces you belong to
`workspace create --name NAME`	Create a workspace
`workspace detail <id>`	Show a workspace
`workspace members <id>`	List members and roles
`workspace audit <id>`	Audit trail for the workspace

project · folder · file

Command	Description
`project list · create · detail`	Manage projects
`project tree <id>`	Files and folders in a project
`folder list · detail · move`	Manage folders
`file upload --project <id> PATH`	Upload a file
`file download <id> --out PATH`	Download a file

ai · search · notification · dashboard

Command	Description
`ai chat "..." [--project-id] [--format pdf\|docx\|md]`	Ask the assistant; can create files
`ai chats list · get · delete`	Manage chat sessions
`ai models list · set`	List / choose the AI model
`ai credits`	Show remaining AI credits
`search semantic "query"`	Natural-language search across the workspace
`notification list · read · read-all`	Manage notifications
`dashboard stats · user-metrics · activity`	Workspace analytics

builder · tool · admin

Command	Description
`builder list · create · detail · public`	Manage builder records (guides, Q&A, prompts…)
`tool video info\|download\|job "URL"`	YouTube / Instagram clip download
`tool convert FILE --to pdf\|docx\|rtf`	File conversion
`tool image models · generate "prompt"`	AI image generation
`admin users list · stats …`	Admin operations (requires --allow-admin)
`config list\|get\|set\|use`	Configuration and profiles
`health · completion bash\|zsh\|fish`	Health check and shell completion

The full machine-readable command reference (73 commands, generated from the CLI itself) ships as cli_reference.json in the repository.

worked example

# Upload a file and ask the assistant to summarise it
cli-anything-thinkflyflow file upload ./report.pdf --project-id 1f78666c-... --json
cli-anything-thinkflyflow ai chat "Summarise report.pdf" --json | jq -r '.data.reply'

Agent & automation use

Every command supports --json, which returns a stable envelope { "status": <int>, "data": <payload> }. This makes the CLI easy to drive from scripts, CI, and AI agents.

pipe into jq

# List projects and extract ids
cli-anything-thinkflyflow project list --json | jq -r '.data[].id'

# Create a weekly report and capture the file id
id=$(cli-anything-thinkflyflow ai chat "Build my weekly report as a PDF" --json | jq -r '.data.file_id')
echo "Created: https://thinkflyflow.laureljar.com/item/$id"

always preview destructive actions

cli-anything-thinkflyflow file delete <id> --dry-run
# [dry-run] DELETE /files/<id> — no changes made

Troubleshooting

Symptom	Fix
401 Unauthorized	Token missing/expired. Run auth login, or export THINKFLYFLOW_TOKEN (PAT).
404 on every call	Base URL must already include /api/v2. Set api_url without a trailing path.
429 Too Many Requests	Rate limited — the CLI backs off automatically; reduce --concurrency.
Wrong environment	Check cli-anything-thinkflyflow config list and --profile test vs prod.
Empty tables in scripts	Add --json for machine output; --table is for humans only.

Need the raw HTTP contract? See the REST API documentation.