Overview

The Farseer CLI is a command-line tool for managing Farseer tenants directly from your terminal. It enables a professional development workflow for building and maintaining Farseer Apps — with bidirectional file sync, local execution, and AI assistant integration.

Combined with the farseer-client TypeScript SDK, the CLI gives developers everything they need to write, test, and deploy automation scripts without leaving their code editor.

Key Capabilities

Bidirectional Sync — Pull and push scripts between your local folder and Farseer instances with diff and conflict detection
Local Development — Run apps locally with automatic credential injection — no hardcoded credentials needed
App Management — Create, configure, run, and delete apps from the command line
Model Inspection — List variables, dimensions, formulas, and export data to CSV
AI Integration — Claude, Cursor, and other AI assistants can interact with Farseer via MCP (Model Context Protocol)

Prerequisites

Node.js version 18.0 or higher
npm (included with Node.js)
A Farseer account with access to at least one tenant
A code editor (VS Code, Cursor, or similar) with TypeScript support recommended

Installing the CLI

Install the Farseer CLI globally via npm:

npm install -g farseer-cli

Verify the installation:

farseer --version

Authentication

The CLI supports two authentication methods. Browser login (OAuth) is recommended as it provides full access to all features including app management.

Browser Login (Recommended)

farseer login

This opens your default browser to the Farseer login page. After successful authentication, the CLI stores your tokens securely in ~/.farseer/config.json. Tokens are automatically refreshed when they expire.

If your organization uses a custom authentication realm:

farseer login --realm your-realm

API Key Login

Alternatively, authenticate with an API key (supports file sync operations only — app management requires browser login):

farseer login --api-key

You will be prompted for your tenant ID, organization, and API key. You can also configure it directly:

farseer config set my-tenant --api-key sk_xxx --org my-org

Verifying Authentication

Check your current authentication status at any time:

farseer whoami

Setting Up the Development Environment

Step 1: Check Out a Tenant

Select the Farseer tenant you want to work with. This sets the default tenant for all subsequent commands:

farseer checkout my-org my-tenant

Where my-org is your organization subdomain (e.g., acme for acme.farseer.io) and my-tenant is the workspace name.

This command verifies your authentication and automatically pulls all files and app configurations from the remote instance.

Step 2: Understand the Project Structure

After checkout, the CLI creates the following local folder structure:

farseer-apps/
  my-tenant/
    package.json            # Auto-generated with Farseer dependencies
    .farseer-sync.json      # Sync state (do not edit manually)
    files/
      Scripts/
        my-import-script.ts
        helpers/
          utils.ts
      Data/
        config.json
    apps/
      My Import App.json
      Sync Actuals.json

Folder / File	Purpose
`files/Scripts/`	Your TypeScript/JavaScript app scripts — maps to the Files > Scripts folder on the Farseer instance
`files/Data/`	Data files (JSON, CSV, etc.) — maps to Files > Data
`apps/`	App configurations as JSON files — each file defines an app's entrypoint, arguments, and actions
`package.json`	Auto-generated with standard Farseer dependencies including `farseer-client`
`.farseer-sync.json`	Internal sync state used for three-way merge — do not edit

Step 3: Install Dependencies

Navigate to the tenant folder and install the npm dependencies:

farseer install

This runs npm install in your tenant directory, installing farseer-client and all other standard dependencies.

Writing Apps

Farseer Apps are TypeScript scripts that use the farseer-client SDK to interact with the Farseer API. They can import data, transform values, sync with external systems, and automate workflows.

Basic Script Structure

Create a new script in files/Scripts/:

import * as farseer from 'farseer-client';const client = new farseer.FarseerClient();
await client.initializeTagMap();// Your app logic here
const variables = client.getVariables();
console.log(`Found ${variables.length} variables`);// Example: export variable data
const data = await client.exportVariableToCsv('Revenue', {
  query: 'Revenue',
  dimensions: ['Months', 'Years', 'Products']
});
console.log(data);

No Hardcoded Credentials

When using the CLI, new FarseerClient() with no arguments is all you need. The CLI automatically injects credentials via environment variables (TENANT_ID, FARSEER_URL, FARSEER_API_KEY or FARSEER_ACCESS_TOKEN) when running locally.

Initializing the Tag Map

Most operations require the tag map to be initialized first. This loads variables, dimension tables, and members into memory:

await client.initializeTagMap();

Call this once at the start of your script. Results are cached for the duration of execution.

Common Operations

Operation	Method
List variables	`client.getVariables()`
List dimension tables	`client.getDimensionTables()`
Load dimension data	`client.loadDimensionTable('TableName')`
Export variable to CSV	`client.exportVariableToCsv('Name', options)`
Create an import job	`client.createImportJob(config)`
Evaluate a formula	`client.evaluateFormula('expression', filters)`
Upload a file	`client.saveArqueroTableAsCsv(table, path)`
List users	`client.getUsers()`

For the complete SDK reference with detailed examples, see the Farseer Client Documentation.

Running Apps Locally

The CLI can run apps locally with automatic credential injection — no need to configure FarseerClient constructors manually.

Running an App

Run a configured app by name:

farseer run My Import App

You can pass arguments to override the app's default parameters:

farseer run My Import App --arg "Year=2025" --arg "Mode=full"

Running a Script Directly

Run any script file without a configured app wrapper:

farseer run-script files/Scripts/my-script.ts

Both commands inject credentials automatically and execute the script using tsx from your tenant's working directory.

Syncing Files with Farseer

The CLI provides a Git-like workflow for keeping local scripts in sync with the Farseer instance.

Pulling Changes

Download the latest files and app configurations from the remote instance:

farseer pull

Use --all to include all file types (not just scripts):

farseer pull --all

Pushing Changes

Upload your local changes back to Farseer:

farseer push

The CLI shows a diff summary and asks for confirmation before uploading. Use -y to skip the confirmation prompt.

Checking Status and Diffs

See what has changed locally vs. remotely:

farseer status

View a specific file's diff:

farseer diff Scripts/my-script.ts

Conflict Resolution

When both local and remote versions of a file have changed, the CLI detects the conflict and offers interactive resolution options: keep local, keep remote, or keep both (creating a .remote copy for manual merging).

Managing Apps from the CLI

Manage the full lifecycle of Farseer Apps without opening the browser.

Command	Description
`farseer app list`	List all apps on the current tenant
`farseer app show My App`	View app details (entrypoint, arguments, actions)
`farseer app create My New App`	Create a new app
`farseer app configure My App --entrypoint Scripts/main.ts`	Set the app's entrypoint script
`farseer app configure My App --add-arg "Year=2025"`	Add a default argument
`farseer app delete My App --force`	Delete an app (requires `--force` flag)

Inspecting the Model

The CLI provides read access to the entire model structure — useful for understanding the data model before writing scripts.

Variables

# List all variables
farseer variables list# Get details for a specific variable (dimensions, formula, rollup type)
farseer variable details Revenue# Export variable data to CSV
farseer variable export Revenue --format csv --output revenue.csv

Dimensions

# List all dimension tables
farseer dimensions list# Get table details with members
farseer dimension details Products --members 50# List members of a table
farseer dimensions members Products

Full Model Export

# Export the entire model structure as JSON
farseer model --json

Sheets and Dashboards

# List sheets and dashboards
farseer sheets list
farseer dashboards list# Get sheet data
farseer sheets data "Revenue Plan"# Get dashboard configuration
farseer dashboards show "Management Report" --tiles

Formulas and Cells

# Evaluate a formula expression
farseer formula eval "sum(Revenue)" --filter "Years=2025"# Query cell values
farseer cells query --variable Revenue --dimension "Products=Widget A" --dimension "Years=2025"# Update a cell value
farseer cells update --variable Revenue --dimension "Products=Widget A" --dimension "Months=Jan" --value 50000

AI Integration (MCP)

The Farseer CLI includes a built-in MCP server (Model Context Protocol) that allows AI assistants like Claude, Cursor, and Claude Code to interact with Farseer directly.

Setting Up MCP

Add the following to your AI assistant's MCP configuration file:

{
  "mcpServers": {
    "farseer": {
      "command": "farseer",
      "args": ["mcp-server"]
    }
  }
}

AI Assistant	Config File Location
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
Cursor	`.cursor/mcp.json` in your project root
Claude Code	`.mcp.json` in your project root

Or simply ask Claude: "Set up farseer MCP server" — it will configure everything automatically.

What AI Can Do

With MCP enabled, your AI assistant has access to 30+ tools covering:

Sync — pull, push, status, diff files
Apps — list, create, configure, run, and delete apps
Model — export model, list variables/tables, get details, create/update variables and dimension members
Data — export variable data, create import jobs, upload files
Sheets & Dashboards — list, inspect, read and write sheet data
Cells — query and update individual cell values

This means you can ask your AI assistant to do things like:

"Inspect the model and write me an import script for sales data"
"Export Revenue data for 2025 as CSV"
"Create a new app called Data Sync and configure it to run my-script.ts"
"What variables use the Products dimension?"

Farseer Client SDK

The farseer-client TypeScript SDK is the foundation for all Farseer Apps. It provides type-safe access to the full Farseer API with high-level abstractions for common operations.

Feature	Details
API Coverage	37 API modules with 469+ TypeScript models
Data Processing	Built-in Arquero integration for data transformation
Authentication	Environment variable auto-config, direct constructor, or custom config object
Bundled Libraries	Arquero, Axios, ExcelJS, MSSQL driver
Requirements	Node.js ≥ 18, TypeScript ≥ 5.0 recommended

For the complete API reference, guides, and code examples, visit the Farseer Client Documentation.

Quick Reference

Getting Started

npm install -g farseer-cli     # Install the CLI
farseer login                   # Authenticate via browser
farseer checkout my-org my-tenant  # Select a tenant
farseer install                 # Install npm dependencies
farseer pull                    # Download files and apps

Daily Development Workflow

farseer pull                    # Get latest from remote
# ... edit scripts in your editor ...
farseer status                  # See what changed
farseer run My App              # Test locally
farseer push                    # Upload changes to Farseer

All Commands

Category	Commands
Auth	`login`, `logout`, `whoami`
Tenant	`checkout`, `config set/remove/list/show/test`
Sync	`pull`, `push`, `status`, `diff`, `files list`
Apps	`app list/show/create/configure/delete`, `run`, `run-script`
Variables	`variables list/create/update`, `variable details/export`
Dimensions	`dimensions list/members/create-member/delete-member`, `dimension details`
Sheets	`sheets list/show/data/set-data`
Dashboards	`dashboards list/show`
Cells	`cells query/update`
Formula	`formula eval`
Model	`model`
AI	`mcp-server`

Troubleshooting

Issue	Solution
Authentication expired	Run `farseer login` to re-authenticate. Tokens auto-refresh, but may expire after extended inactivity.
App management not working with API key	App management requires browser login (OAuth). Run `farseer login` instead of using `--api-key`.
Push rejected	Remote has changes you don't have locally. Run `farseer pull` first, resolve any conflicts, then push again.
`FarseerClient()` not connecting	Make sure you're running via `farseer run` or `farseer run-script` so credentials are injected. Check `farseer whoami` to verify auth.
MCP server not responding	Verify the CLI is installed globally (`which farseer`). Restart your AI assistant after config changes.

Farseer CLI & Developer Guide