flowus-cli

Command line tools for the FlowUs V2 API.

Repository: next-space/flowus-cli

Requirements

• Node.js 20 or newer.
• A FlowUs account for interactive login, or a FlowUs V2 API token for automation.

Install

npm install -g flowus-cli

Authentication

Choose a login method:

# Choose interactively.
flowus login

# Desktop/browser OAuth login.
flowus login --browser

# Manual integration token setup for servers, SSH sessions, and CI.
flowus login --manual

flowus login --manual prints the FlowUs integration URL, token creation steps, and a shell-specific recommendation for persisting FLOWUS_TOKEN. For automation, set FLOWUS_TOKEN in the process environment or pass --token to individual commands. Credential precedence is --token, then FLOWUS_TOKEN, then the token saved by flowus login. If FLOWUS_TOKEN and saved login credentials both exist, flowus whoami uses FLOWUS_TOKEN and prints a warning to stderr.

flowus whoami

Usage

flowus login
flowus login --manual
flowus whoami
flowus --json page get <page_id>
flowus --json page create --body page.json --idempotency-key request-1
flowus --json page update <page_id> --body patch.json --if-match W/"version"
flowus --json page property get <page_id> <property_id>
flowus --json block children <block_id>
flowus --json block append <block_id> --body children.json
flowus --json block update <block_id> --body patch.json
flowus --json database query <database_id> --body query.json
flowus --json database create --body database.json
flowus --json database update <database_id> --body patch.json
flowus --json markdown get <page_id>
flowus --json markdown put <page_id> --file page.md
flowus --json search text "roadmap"
flowus --json search text --body search.json
flowus --json search semantic "roadmap planning"
flowus --json file upload ./roadmap.pdf --parent-page <page_id>
flowus --json block append-file <block_id> --oss-name <oss_name>
flowus --json user get <user_id>
flowus api ls
flowus --json api call GET /v2/users/me

Use flowus logout to remove saved credentials and flowus doctor to inspect local authentication state. Saved credentials are written to ~/.flowus/credentials.json by default. Set FLOWUS_CONFIG_DIR to choose another directory.

Use --json for stable machine-readable stdout. Human-readable diagnostics are written to stderr. Use flowus help <command...> to inspect command-specific options such as pagination, search body files, and documented request headers.

Command Coverage

• page: get, create, update, and read page property values.
• block: get, list children, append children, update, and append file blocks.
• database / db: get, query, create, and update databases.
• markdown: get or replace page content as Markdown.
• search: keyword search and semantic search.
• file: upload local files for a parent page.
• user: read users.
• api ls: list supported public FlowUs V2 API endpoints.
• api call: call documented FlowUs V2 endpoints that are not yet wrapped by a domain command.

Delete operations are intentionally not exposed. flowus api call DELETE ... is rejected as unsupported by the CLI.

Maintaining API Coverage

When adding, removing, or changing supported FlowUs API endpoints, update these together:

• src/commands/api.ts: supportedApiEndpoints, including path/query/body metadata for flowus api ls.
• src/help-content.ts: agent-facing help text, examples, and request-body guidance.
• Domain command modules when a first-class command wraps or stops wrapping an endpoint.
• CLI tests for routing, help output, and api ls JSON/plain/table output.
• Repository docs and FlowUs skills when behavior changes.

Run npm run check from the workspace root before release.

License

MIT