CLI Reference

The fluidsoul CLI gives you full access to the fluidsoul API from your terminal — 28 commands covering events, context, rules, users, analytics, and workspace management.

Installation

npm (recommended):

npm install -g @fluidsoul/cli

This installs a prebuilt native binary for your platform. Works on macOS (x64, ARM64), Linux (x64, ARM64), and Windows (x64).

From GitHub Releases:

Download the prebuilt binary for your platform from GitHub Releases and add it to your PATH.

From source (requires Rust toolchain):

cargo install --path crates/fluidsoul-cli

Setup

Initialize config

fluidsoul init

Creates ~/.fluidsoul/config.toml with default settings.

Authenticate (Clerk JWT)

fluidsoul login

Stores a Clerk session token for admin commands (workspace management, user listing).

Set API token

fluidsoul token set fs_tok_xxxxxxxxxxxx

Sets the workspace API token used for public API commands.

Verify connectivity

fluidsoul health

Checks that your API URL is reachable and returns ok.

Show current config

fluidsoul whoami

Displays your configured API URL, workspace ID, token status, and API connectivity.

Configuration

View config

fluidsoul config view

Set a config value

fluidsoul config set api_url https://api.fluidsoul.io
fluidsoul config set workspace_id aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Valid keys: api_url, workspace_id, token, clerk_token.

Environment variable overrides

Environment variables take precedence over config file values:

Global flags

These flags work with any command:

Events

Send an event

fluidsoul events send \
  --user-id usr_123 \
  --event-type feature_accessed \
  --metadata '{"feature_name": "analytics"}'

Auth: API token

Stream events (SSE)

fluidsoul events stream

Streams real-time events for the configured workspace via Server-Sent Events.

Auth: API token (requires admin workspace)

Context

Get user context

fluidsoul context get usr_123

Returns the computed context profile for a user — category, feature priorities, engagement level, and more.

Auth: API token

Refresh user context

fluidsoul context refresh usr_123

Re-runs the rules engine on the user's events and updates their context profile.

Auth: API token

View context history

fluidsoul context history usr_123 --limit 10

Shows historical context snapshots and dimension transitions.

Auth: API token

Segments

Query users by segment

fluidsoul segments query \
  --dimension user_category \
  --value analyst \
  --limit 50

Returns users matching a segment dimension and value.

Auth: API token

Users

List users

fluidsoul users list --search "usr_" --limit 20
fluidsoul users list --dimension user_category --value analyst

Lists users with context summary. Supports search and dimension filtering.

Auth: Clerk JWT (admin)

View user detail

fluidsoul users detail usr_123

Shows detailed user profile including context, events, and history.

Auth: Clerk JWT (admin)

Export user data (GDPR)

fluidsoul users export usr_123
fluidsoul users export usr_123 --output export.json

Exports all stored data for a user. Use --output to write to a file.

Auth: API token

Delete user data (GDPR)

fluidsoul users delete usr_123 --confirm

Permanently deletes all data for a user. Requires --confirm flag — this is irreversible.

Auth: API token

Rules

View rules config

fluidsoul rules get

Displays the current workspace rules configuration.

Auth: API token

Update rules config

# From a file
fluidsoul rules set --file rules.json

# From stdin
cat rules.json | fluidsoul rules set --stdin

Updates the workspace rules configuration. See Configuring Rules for the schema.

Auth: API token

Analytics and Outcomes

View workspace analytics

fluidsoul analytics

Shows aggregate workspace metrics — user counts, event counts, and segment breakdowns.

Auth: API token

View outcome rates

fluidsoul outcomes --outcome-type conversion --dimension user_category

Shows outcome/conversion rates broken down by a segment dimension.

Auth: API token

Audit Logs

View logs

fluidsoul logs --limit 50 --offset 0

Paginated audit trail of all significant actions in the workspace.

Auth: API token

Workspace Management (Admin)

These commands use Clerk JWT authentication, not workspace API tokens. Run fluidsoul login first.

Create a workspace

fluidsoul workspace create "My App"

List workspaces

fluidsoul workspace list

View workspace details

fluidsoul workspace info

Shows details for the configured workspace.

Generate API token

fluidsoul workspace token generate

Generates a new API token for the workspace. This invalidates the previous token. Requires owner role.

List members

fluidsoul workspace members

Lists all members of the configured workspace.

Quick Reference