FineBI CLI

FineBI CLI is a dynamic command line client for FineBI plugin capabilities. It handles local config, username/password login, capability cache, --help/-h, and HTTP command forwarding.

Array options take a JSON array as one argument, for example --values '["上海","江苏"]' for geographic matching. The CLI parses the array and validates its item schema before sending the request; comma-separated text is not an array.

Changelog

2.0.16

• Check for managed Agent Skill updates from the connected FineBI plugin before remote tasks. Updates include the bundled CLI.

2.0.14

• Fix the Web app login return flow after a session expires.
• Reject lossy JSON numbers and duplicate dashboard filter keys before sending requests.
• Add tree and numeric range controls to the Web app template. JSON filter overrides and clearing require a compatible FineBI HTTP endpoint.
• Update the bundled Skill with mixed filter examples, saved composite conditions, published dashboard candidate queries, and time-group labels. These dashboard capabilities require a compatible server plugin.

2.0.13

• Update the CLI and bundled Skill version metadata.

2.0.12

• Update the bundled Skill to return dashboard query results immediately after necessary checks, limiting follow-up queries to gaps that affect answer correctness.

2.0.11

• Use the plugin's password authentication endpoint to issue Access Keys, without saving session tokens locally. Password login requires a compatible server plugin and rejects --no-access-key.
• Include the server's read/write metadata in dynamic command --help --json output.
• Update the bundled Skill's command discovery and dashboard query guidance for source selection, filters, pagination, and metric queries.

2.0.10

• Fix Windows system command resolution for app authentication, configuration permissions, and browser authorization when PATH contains conflicting executables.
• Add the modern web app layout and its example configuration.
• Align web app filter defaults and clearing behavior, and automatically restart Vite when application configuration changes.
• Update the bundled Skill for dashboard search, query results, and layout guidance.

2.0.9

• Automatically synchronize managed Agent Skills and their bundled CLI during npm installation and upgrades, preserving local edits and backing up updated Skills.
• Add table pagination and viewport-based widget loading to the bundled web app template.
• Clarify command discovery and dashboard source selection in CLI help and the bundled Skill.
• Isolate app auth sessions from PC browser single-login policies using the OTHER terminal, while preserving expiry and Access Key revocation. Requires server plugin 1.0.45 or later; re-run app auth after upgrading.

2.0.8

• Allow web app filters to explicitly clear dashboard control defaults by sending an empty array. The FineBI platform's HTTP widgets/query endpoint must support this protocol; upgrading the CLI plugin alone is insufficient.

2.0.7

• Add a changelog to the package README.

2.0.6

• Add app auth to export a development session from an authenticated CLI profile to a web app project's .env.local. This requires a compatible FineBI server plugin.
• Simplify the web app development proxy to reuse the exported session and report expired or missing authentication.

2.0.5

• Update the bundled Skill's web app workflow to continue when browser control is unavailable and clearly report browser checks that could not be performed.

2.0.4

• Prefer pnpm for installing web app dependencies, with npm used when pnpm is not installed.

Install

npm install -g @finebi/finebi-cli --registry=https://registry.npmjs.org/

This package includes the CLI and the complete finebi-cli-agent Skill. Contact service personnel to obtain the FineBI server plugin and have an administrator install or enable it before connecting to FineBI.

For the five-step installation, authentication and verification flow, see the bundled Agent installation guide.

Usage

Built-in help is always available and does not require server config, login, or a capability refresh:

finebi-cli --help
finebi-cli --help --json
finebi-cli config set --help
finebi-cli auth login --help
finebi-cli capability refresh --help
finebi-cli version --help
finebi-cli config --help
finebi-cli auth --help
finebi-cli capability --help
finebi-cli app --help

Dynamic resource help, such as finebi-cli <resource> --help, is loaded from the FineBI capability cache. Login refreshes this cache automatically:

finebi-cli config set base-url http://localhost:37799/webroot/decision
finebi-cli auth login --username 1
finebi-cli version
finebi-cli --help
finebi-cli <resource> --help
finebi-cli <resource> <command> [options]

Create and inspect a local dynamic web app project without connecting to FineBI:

finebi-cli app create --name sales-dashboard --path D:\work --layout cockpit
finebi-cli app inspect --path D:\work\sales-dashboard

app create copies the bundled web-app template, sets the project npm name, and records the template version in public/app-config.json. It rejects an existing destination and does not install dependencies or run project scripts. app inspect reads a JSON object and reports a configuration summary with configValidated: false and remoteValidated: false. Optional --strict validates against the CLI bundled template rules, which may not match custom app extensions. Inspection is not an acceptance gate; use the generated project tests, build and real browser checks to verify the application.

--layout accepts overview (default), workbench, or the green cockpit layout. Cockpit shares the existing Cookie query and authentication flow, with configurable KPI/chart/table bindings, independent retries, and a custom month picker. The generated README and examples/cockpit.config.json describe the placeholder bindings; no business data or credentials are bundled. Published sources require directoryEntryId and a platform HTTP endpoint that supports directory permissions; failed queries never switch sources.

Use --layout retail for a warm paper-style retail brief with horizontal navigation, a KPI strip, and blue/orange charts. examples/retail.config.json contains placeholder retail bindings; see the generated design guide for explicit KPI and month-label formats. Creation leaves the project unbound and does not query a server.

With an authenticated CLI profile, run finebi-cli app auth --path D:\work\sales-dashboard --profile test to export a FineBI session to the project's .env.local. This command connects to FineBI and requires a plugin supporting /api/bi-cli/dev-session. It preserves other env settings, checks the project target against the profile, saves the actual expiry, and prints only non-secret metadata. The exported session has the account's full platform permissions. Keep the file private and out of version control.

Start or restart Vite after the command succeeds. The proxy only reuses the supplied token. A missing or expired session produces an AUTH_REQUIRED log hint; an active Agent or the user runs app auth again and restarts Vite. The proxy never invokes the CLI, logs in, or opens a browser. Use the CLI's auth login --browser to obtain an Access Key when needed. See the generated authentication guide and Agent workflow. Existing projects need the updated development proxy; app auth does not upgrade their source files.

Run finebi-cli capability refresh manually when backend commands changed, the cache expired, or you want to force a reload.

Resource and command help show their detailed descriptions when the server provides them, in both text and --json output. Older cached capabilities without descriptions still work. The server omits resource groups with no enabled commands; refresh capabilities after upgrading the plugin to see the current command surface.

Dynamic command --help --json includes data.mutation from the capability manifest alongside parameter and response schemas: false means read-only and true means mutating. Missing metadata stays absent, rather than defaulting to read-only. Help can display expired cached capabilities; check cache validity when its status is unknown and reuse valid discovery results across tasks. The Agent discovery workflow describes when to refresh or read the full manifest.

capabilities remains a compatibility alias for capability refresh, with unchanged execution and response format. Use capability refresh in new workflows; the alias is not listed among common commands.

config set capability-ttl-ms <ms> applies to the next capability refresh. Existing cache expiry stays unchanged; the setting command reports this and gives a refresh command for the selected profile. Use capability info to inspect the current expiry.

JSON file inputs reject numeric tokens whose decimal value changes during JavaScript parse/serialization, including overflow and underflow. Use values supported by the command's precision contract; numeric strings are accepted only when its schema allows them.

For dashboard component queries, use repeatable inline filters or a JSON file (mutually exclusive):

finebi-cli dashboard data --id <dashboardId> --entry-id <entryId> --filter "合同付款类型=分期付款" --filter "是否已经交货=是" --page-size 5
finebi-cli dashboard data --id <dashboardId> --entry-id <entryId> --filter "日期=2026-11-05" --filter "门店=[]"
finebi-cli dashboard data --id <dashboardId> --entry-id <entryId> --filters-file filters.json --page-size 5

--filter "门店=[]" clears that control's filter for the current query. To select the literal text [], use --filters-file with {"门店":["[]"]}. Scalar control clearing requires the platform Provider's empty-array protocol; tree, number-range and composite controls are cleared in the authorized query copy. Check queryContext.clearSupported; see the dashboard data contract.

Tree dropdown/list controls (controlType=TREE/TREE_LIST) use nested paths, such as {"省市":[["浙江","杭州"]]}. Tree tags (TREE_LABEL) use per-level selections, such as {"省市":[["浙江","江苏"],[]]}, where an empty inner array leaves that level unrestricted. Number ranges/sliders use a complete object, such as {"流水":{"min":100,"max":null,"closeMin":true,"closeMax":false}} for [100,+∞). Submit these through --filters-file, together with all scalar overrides; inline --filter cannot be combined with the file. Mixed examples, date formats and all composite literal kinds are in the Skill filter examples.

Composite filters use --filters-file with {"组合":{"values":{"$.0":["上海"],"$.1.0":100}}}. Obtain native leaf paths and literal kinds from the same source's dashboard info → queryContext.compositeInputs. Saved fields, operators, AND/OR groups and filter levels stay fixed; omitted leaves retain saved values. {"组合":[]} clears the entire composite in the authorized query copy. Composite overrides apply to data components only; saved condition trees must fit within 64 levels, counting the root and leaves. Duplicate keys in any filter JSON object are rejected. See the input contract.

Filter names come from dashboard info control entries' filterName. Detail, group and cross tables all use --page for a one-based target row page. Cross tables additionally use --column-page for a one-based target column page. Both axes default independently to 1; specify both to preserve the other position, for example --page 3 --column-page 2. --page-size controls rows or groups per page, including header-expand tables.

For sequential navigation, add or subtract 1 from the last successful data.page or data.columnPage, checking hasNext/hasPrevious or hasColumnNext/hasColumnPrevious first. Repeat the same filters, dimension selection, page size and source for each independent query, and explicitly preserve the other axis for cross tables. Restart at page 1 when query conditions change.

Ordinary tables query the first page when pagination options are omitted. Header-expand tables keep their initial view when all pagination options are omitted; specifying --page, --column-page or --page-size requests pagination with the saved expansion configuration. Charts are unpaged. Parameter and result details are defined in the dashboard data contract. The platform must provide the Provider pagination contract; refresh capabilities after updating the plugin.

For temporary field selection, first read the target instance's field directory:

finebi-cli dashboard info --id <dashboardId>
finebi-cli dashboard data --id <dashboardId> --entry-id <entryId> --dimension-ids '["<dimensionDId>","<measureDId>"]' --filter "合同付款类型=分期付款"
finebi-cli dashboard data --id <dashboardId> --entry-id <entryId> --dimension-ids '[]'

Use entries[].queryFields[].dId where selectable=true; this is a component-local key, not a dataset fieldId or field name. queryFields includes disabled fields and reports their saved used flag. Omit --dimension-ids to keep the saved selection. The list is a complete whitelist of dimensions and measures: unlisted selectable fields are disabled. Include measure dIds explicitly to keep their output; selecting only measures disables selectable dimensions. An explicit [] disables all selectable dimensions and measures; a detail table returns no columns or rows. Existing filters remain effective. Empty output columns do not imply that native pagination totals are zero.

For a published dashboard, pass the same --directory-entry-id to dashboard info and dashboard data, and use dIds from that source. Installing this npm package updates only the client and bundled Skill. These commands require a server plugin and platform Provider supporting the complete dimension-and-measure whitelist; the plugin directly depends on the dimension-selection and published-source APIs. Refresh capabilities after the server update.

Multiple environments

Create an environment by logging in with its name and address:

finebi-cli auth login --profile test --base-url https://test.example.com/webroot/decision --browser
finebi-cli auth login --profile prod --base-url https://prod.example.com/webroot/decision --username admin --password-stdin
finebi-cli auth list
finebi-cli auth use test
finebi-cli capability info --profile prod
finebi-cli auth info --profile prod
finebi-cli config set timeout-ms 60000 --profile prod
finebi-cli auth logout --profile prod
finebi-cli auth remove prod

Successful login selects that environment as the default; add --no-use to keep the existing default. Login to an existing name reuses its address unless overridden. A new name requires --base-url or FINEBI_BASE_URL and never inherits another environment's identity. Failed authentication leaves existing environments and the default unchanged.

Selection order is --profile > FINEBI_PROFILE > saved default. The option works before or after the command. Ordinary commands never create missing environments or change the default. Names are case-sensitive, 1–64 ASCII letters/digits/underscores/hyphens, beginning with a letter or digit. auth list shows local metadata only, not a live authentication check. JSON responses identify the selected environment in meta.profile.

Each environment has separate credentials, connection settings and capabilities. Changing its saved base-url clears its credentials and cache. Temporary URL/token overrides do not change saved configuration; a different URL never inherits saved credentials. Requests with temporary credentials fetch capabilities for that invocation without overwriting a saved cache. Explicit session tokens take precedence over saved Access Keys.

auth logout revokes the selected environment's saved Key and keeps its connection settings. auth remove <name> and config clear --profile <name> delete only that local environment and cache, without revoking server credentials. Removing the default does not automatically select another saved environment. Persistent configuration and logout operations use the selected saved environment, not connection override variables.

Use auth remove <name> to delete a local environment. config clear --profile <name> remains a compatibility alias with unchanged execution and response format; it is available through direct command help but omitted from the config command list. Neither command revokes server keys; run auth logout --profile <name> first when revocation is required.

Existing single-environment configuration is exposed as default; read-only commands do not rewrite it. Multi-environment writes migrate it while preserving its credentials and default capability cache. See the command contract for the complete behavior.

Access Key

Password login sends credentials to the plugin's server-side authentication endpoint, which applies FineBI login policy and returns a CLI Access Key. Browser authorization saves the Key received after approval. Business commands use X-BI-CLI-Access-Key; the server also accepts X-FineBI-CLI-Access-Key as a compatibility alias.

• Password login always issues an Access Key. --no-access-key is rejected. The CLI stores only the Access Key and username; password-login session tokens and their expiry are never written to config.json.
• auth info shows authMode (access-key / session-token / none) with credentials masked. The session-token mode remains available for explicit temporary --token requests.
• auth logout revokes the saved Key before clearing local credentials. Failed revocation preserves credentials for retry; --force permits local cleanup without confirmed server revocation.

The authentication contract defines issuance, profile descriptions, headers, compatibility and failure behavior. Local credential storage is described under Local Files.

finebi-cli auth login --username 1
finebi-cli auth info
finebi-cli auth logout
finebi-cli auth logout --force

Agent discovery flow:

finebi-cli --help --json
finebi-cli config set base-url http://localhost:37799/webroot/decision
finebi-cli auth login --from-env
finebi-cli system command-index --json
finebi-cli <resource> <command> --help --json
finebi-cli <resource> <command> [options] --json

system command-index returns the whole command surface as one compact index grouped by resource ([write] marks mutations, [creates] additionally marks resource creation; output is bounded to 8KB). Start with it instead of enumerating every resource's help, and open --help only for the commands you actually invoke.

For complex file-based resources, do not expect command help to contain a complete source example. widget template returns a Widget JS DSL source template selected by chart type and scenario; dashboard template returns a Dashboard JS DSL example script with named placeholders and a variable contract. Their add and update commands accept JS DSL source files. Other resources may still expose writable JSON templates according to their dynamic command help.

Agent Skills

Install the bundled finebi-cli-agent Skill into your Agent's directory:

finebi-cli install-skill --list
finebi-cli install-skill --agents codex,cursor

Run finebi-cli install-skill in an interactive terminal to choose Agents. Non-interactive use requires --agents. Supported IDs are claude-code, codex, dsh, cursor, gemini-cli, github-copilot, opencode, cline, windsurf, workbuddy, trae, trae-cn, openclaw, roo, and qwen-code. Custom CODEX_HOME, CLAUDE_CONFIG_DIR, DSH_HOME, WORKBUDDY_HOME, and XDG_CONFIG_HOME directories are respected. For DeepSeek Harness, use finebi-cli install-skill --agents dsh; Skills are installed to ~/.dsh/skills by default, or <DSH_HOME>/skills when DSH_HOME is set.

For WorkBuddy, use finebi-cli install-skill --agents workbuddy; Skills are installed to ~/.workbuddy/skills by default, or <WORKBUDDY_HOME>/skills when WORKBUDDY_HOME is set. Set WORKBUDDY_HOME to match the configuration root used by your WorkBuddy installation.

Skill installation is local and does not require a server connection or credentials. It copies the Skill included in this installed npm version, including its own CLI runtime. Restart your Agent or refresh its Skills after installation. With no installation records, npm installation leaves Agent directories untouched; choose Agents with install-skill first.

To update, install the latest CLI package:

npm install -g @finebi/finebi-cli@latest --registry=https://registry.npmjs.org/

npm postinstall synchronizes managed Skills at their recorded paths, including custom Agent roots even when their environment variables are no longer set. Removed Skills are not recreated, and unrecorded Skills are not adopted. Local edits are preserved. Synchronization errors do not fail the CLI installation. Use --foreground-scripts with npm to see synchronization results; if installation scripts are disabled (for example, with --ignore-scripts), or to retry, run finebi-cli install-skill --agents codex,cursor manually. Refresh Skills or restart your Agent after an update.

After a one-time installation of a Skill with server synchronization, it checks the configured FineBI plugin before remote tasks and reuses successful checks for one hour. A compatible plugin can update the managed Skill in place, including its bundled CLI. The downloaded CLI runs locally, so use a trusted FineBI server and prefer HTTPS. After an update, start a new conversation to load the updated rules. Local edits remain protected.

Installation records use absolute paths. If an older installation recorded a relative Agent root, automatic synchronization reports it without guessing its location. Run install-skill once from the original working directory with the original Agent environment to update that record.

Identical installations are left unchanged. Unmodified managed Skills are backed up and updated automatically. Local edits and installations without a recorded checksum are kept, and the command reports an incomplete installation. To explicitly replace them with a backup:

finebi-cli install-skill --agents codex --replace

Backups are stored under ~/.finebi-cli/skill-backups/; installation records are in ~/.finebi-cli/installation.json. The command preserves other records and does not change authentication or connection configuration. The Skill follows the discovery flow above and treats dynamic command help as the source of truth after capability refresh.

Output

FineBI CLI keeps two audiences in mind:

• Human-facing built-in commands print concise text by default.
• Agent and script integrations can add --json to get the full JSON envelope.
• Dynamic business commands use backend capability display hints for human-readable output by default.
• Dynamic business commands can use -f, --format for display formats supported by the command shape.
• --json has priority over display formats and always returns the full JSON envelope.

capability refresh (also capabilities) prints resource/command counts and fetch/expiry times by default. It retains the complete manifest in --json, saved output and the cache. A transient connection fetch reports that the local cache is unchanged. Successful refresh responses include meta.capabilityCache with cached, fetchedAt and nullable expiresAt; TTL setting responses keep data.key/value and add the notice under meta.capabilityTtl.

Large responses can be narrowed before they reach the caller (all three are CLI-side only — they are stripped from the command arguments and never forwarded to the plugin):

• --select <paths> projects the response onto comma-separated dotted paths (arrays use indexes, e.g. data.dsl,warnings,errors.0.message). Output is always JSON and keeps ok / command; an unknown path fails loud with the available top-level keys instead of printing a partial result.
• --max-chars <n> keeps the head and tail of long output with explicit truncation markers (total/omitted character counts plus how to get the full text). The cap is inclusive: markers count against it, so the truncated output never exceeds n characters.
• --save <path> writes the full JSON envelope (projected when --select is used — the human rendering is lossy, so files always hold the complete response) and prints only a short summary: ok / command / saved / chars / warnings. --save wins over --max-chars (the summary is already tiny); a failed write reports INVALID_ARGUMENT with the path instead of a stack trace.

A command that fails is never projected (its data is null, so projection would hide the real error behind Unknown path(s)); --select implies JSON output, including for its own argument errors. Failed commands are still saved when --save is present — the file holds the failure envelope, so scripted consumers never read a stale success from a previous run.

finebi-cli dashboard dsl --id <id> --select data.dsl,warnings
finebi-cli dashboard bean --id <id> --save temp/board.json
finebi-cli subject info --id <id> --json --max-chars 8000

Human-friendly defaults:

finebi-cli version
finebi-cli config get
finebi-cli auth info
finebi-cli capability info
finebi-cli config clear
finebi-cli auth logout
finebi-cli capability clear-cache

Structured output:

finebi-cli version --json
finebi-cli config get --json
finebi-cli auth info --json
finebi-cli capability info --json
finebi-cli <resource> <command> [options] --json

Dynamic display formats:

finebi-cli <resource> <command> [options] -f auto
finebi-cli <resource> <command> [options] -f table
finebi-cli <resource> <command> [options] -f expanded
finebi-cli <resource> <command> [options] -f csv

Dynamic shapes are record-list, detail, tabular-preview, and generic. Java capability metadata declares only the shape and the default format used by auto. Node.js renders these shapes generically from the response data, preserving the returned information instead of hardcoding business command names or command-specific columns.

Environment login:

$env:FINEBI_BASE_URL="http://localhost:37799/webroot/decision"
$env:FINEBI_USERNAME="1"
$env:FINEBI_PASSWORD="your-password"
finebi-cli auth login --from-env

Successful login also attempts to refresh the dynamic capability cache. If the refresh fails, login still succeeds and the CLI prints a warning with finebi-cli capability refresh as the follow-up action.

Browser authorization login:

finebi-cli auth login --browser

This prints a same-server confirmation URL and code to stderr. Open the URL and confirm the code; when the browser is not signed in, the authorization page redirects to the platform login and returns after login. The CLI only sends the browser authorization request fields and saves the returned Access Key after approval; it does not send an existing local credential to the authorization endpoints.

Pipe password through stdin:

echo your-password | finebi-cli auth login --username 1 --password-stdin

Local Files

• Config: %USERPROFILE%\.finebi-cli\config.json
• Capability cache: %USERPROFILE%\.finebi-cli\capabilities.json
• Named environment caches: %USERPROFILE%\.finebi-cli\capabilities-profile-<hex-encoded-name>.json (default uses capabilities.json).

Multi-environment config.json stores schemaVersion: 2, currentProfile (nullable), and a profiles object keyed by environment name. Writes are serialized with a short-lived config.json.lock and atomically replace the configuration file. A lock wait times out after 30 seconds and reports an error without modifying the file.

Concurrent logins to the same environment are rejected using config.json.login-<hex-encoded-name>.lock; different environments may log in concurrently. Locks are released when the operation settles. If a process is forcibly terminated and leaves a lock behind, verify that the owning operation has stopped before manually removing that lock file.

Passwords are not persisted by the CLI. Saved session tokens and Access Keys remain usable credential values in config.json; they are not encrypted at rest. On POSIX, the CLI restricts the directory to 0700 and the file to 0600. On Windows, it attempts to remove inherited ACLs and grant access to the current user, SYSTEM and Administrators; failures emit a security warning. Protect this directory and its backups.