Installation

Quick Install (macOS / Linux)

curl -fsSL https://get.entropyfa.com | sh

The default installer is user-local. It installs entropyfa into ~/.entropyfa/bin, updates your shell profile if needed, and does not require sudo.

System-wide Install (Optional)

curl -fsSL https://get.entropyfa.com | sh -s -- --system

Cargo

cargo install --git https://github.com/Entropy-Financial-Technologies/entropyfa-cli.git entropyfa

From Source

git clone https://github.com/Entropy-Financial-Technologies/entropyfa-cli.git
cd entropyfa-cli
cargo build --release
mkdir -p ~/.entropyfa/bin
install -m 755 target/release/entropyfa ~/.entropyfa/bin/entropyfa

Upgrade

entropyfa upgrade

Checks GitHub for the latest release, downloads the new binary, and replaces the current executable when that path is writable. If your existing install is in a system directory, upgrade falls back to ~/.entropyfa/bin instead of prompting for sudo. The CLI also checks for updates in the background.

Quick Start

30-Second Demo

1. Discover what data is available:

entropyfa data coverage

2. Look up 2026 federal income tax brackets for single filers:

entropyfa data lookup --category tax --key federal_income_tax_brackets --year 2026 --filing-status single

{
  "data": {
    "category": "tax",
    "key": "federal_income_tax_brackets",
    "year": 2026,
    "verification_status": "authoritative",
    "pipeline_reviewed": true,
    "source_origin": "reviewed_artifact",
    "sources": [
      {
        "authority": "Internal Revenue Service",
        "url": "https://www.irs.gov/pub/irs-drop/rp-25-32.pdf"
      }
    ],
    "value": [
      { "rate": 0.10, "min": 0, "max": 12400 },
      { "rate": 0.12, "min": 12400, "max": 50400 }
    ]
  },
  "ok": true
}

3. Compute federal tax on $150k wages:

entropyfa compute federal-tax --json '{"filing_status":"single","income":{"wages":150000}}'

{"data":{"total_tax":36209,"effective_rate":0.1649,"marginal_ordinary_rate":0.24,...},"ok":true}

4. Get the schema for any compute command:

entropyfa compute roth-conversion --schema

5. Run a Roth conversion analysis:

entropyfa compute roth-conversion --json '{"filing_status":"married_filing_jointly","income":{"wages":200000},"traditional_ira_balance":500000,"conversion_amount":50000}'

6. Run a Monte Carlo retirement projection with the optional terminal dashboard:

entropyfa compute projection --visual --json '{"starting_balance":1000000,"time_horizon_months":360,"return_assumption":{"annual_mean":0.07,"annual_std_dev":0.15},"cash_flows":[{"amount":-4000,"frequency":"monthly"}]}'

Commands Reference

data coverage

Discover all available reference data embedded in the binary. Returns categories, keys, available years, required parameters, and related topics.

Usage

entropyfa data coverage

Example Output

{
  "data": {
    "count": 17,
    "entries": [
      { "category": "tax", "key": "federal_income_tax_brackets", "years": [2026], "parameters": ["filing_status"] },
      { "category": "tax", "key": "federal_standard_deductions", "years": [2026], "parameters": ["filing_status"] },
      ...
    ]
  },
  "ok": true
}

data lookup

Look up specific reference data by category, key, year, and applicable parameters. Lookup responses now include the value plus verification metadata and source URLs by default.

Usage

entropyfa data lookup [OPTIONS]

Flags

Flag	Description	Required
--category	Data category (tax, retirement, etc.)	Yes
--key	Data key within category	Yes
--filing-status	Filing status filter	When applicable
--year	Reference year (defaults to latest)	No
--lived-with-spouse-during-year	Required for IRMAA lookups when filing status is married_filing_separately	When applicable

Example

entropyfa data lookup --category tax --key federal_income_tax_brackets --year 2026 --filing-status single

{
  "data": {
    "category": "tax",
    "key": "federal_income_tax_brackets",
    "year": 2026,
    "verification_status": "authoritative",
    "completeness": "full",
    "pipeline_reviewed": true,
    "source_origin": "reviewed_artifact",
    "sources": [
      {
        "authority": "Internal Revenue Service",
        "source_class": "primary",
        "url": "https://www.irs.gov/pub/irs-drop/rp-25-32.pdf"
      }
    ],
    "value": [
      { "rate": 0.10, "min": 0, "max": 12400 },
      { "rate": 0.12, "min": 12400, "max": 50400 }
    ]
  },
  "ok": true
}

Lookup Response Fields

Field	Description
verification_status	Current trust status for the entry: authoritative, corroborated, derived, or placeholder
completeness	Whether the embedded dataset is full or partial
pipeline_reviewed	True when the entry has been promoted through the maintainer verification pipeline
source_origin	Where provenance came from: reviewed artifact or registry metadata
sources	Source documents used for the entry. Pipeline-reviewed entries include URLs by default.
value	The actual reference payload for the requested category/key/params

IRMAA Example

entropyfa data lookup --category insurance --key irmaa_brackets --year 2026 --filing-status married_filing_separately --lived-with-spouse-during-year true

The IRMAA contract distinguishes married-filing-separately taxpayers who lived with a spouse during the year from those who lived apart, because the official CMS and SSA rules use different bracket tables.

Use the global --result-hook-url flag to POST the same JSON envelope to a webhook endpoint.

compute federal-tax

Compute federal income + payroll taxes for a given filing status and income breakdown.

Usage

entropyfa compute federal-tax --json '<JSON>'

When to Use

When a user asks about their federal tax liability, effective tax rate, marginal rate, bracket mechanics, or payroll tax (FICA / SE) consequences.

Schema (What to Gather)

Field	Description	Required
filing_status	single, married_filing_jointly, married_filing_separately, head_of_household, qualifying_surviving_spouse	Yes
income.wages	W-2 wages	At least one income field
income.qualified_dividends	Qualified dividend income	No
income.long_term_capital_gains	Long-term capital gains	No
income.short_term_capital_gains	Short-term capital gains	No
income.taxable_ira_distributions	Taxable traditional IRA distributions	No
income.taxable_pensions	Taxable pension income	No
income.taxable_social_security	Taxable Social Security benefits	No
income.self_employment_income	Self-employment income	No
adjustments	HSA, IRA, student loan interest, other above-the-line adjustments	No
deductions.method	standard or itemized (defaults to standard)	No
deductions.itemized_amount	Aggregate itemized deductions when you already have the final Schedule A total	No
deductions.state_local_income_or_sales_tax	Elected state/local income tax or sales tax amount for Schedule A SALT	No
deductions.real_property_tax	State and local real property taxes	No
deductions.personal_property_tax	Deductible personal property taxes	No
deductions.other_itemized_deductions	Non-SALT itemized deductions to add after the SALT cap is applied	No
deductions.spouse_itemizes	Whether an MFS spouse itemizes, which can force itemized treatment	No

Use either deductions.itemized_amount or the detailed itemized fields, not both. deductions.state_local_income_or_sales_tax is the elected Schedule A income-or-sales-tax amount, not an automatic sales-tax-table calculation.

Example

entropyfa compute federal-tax --json '{"filing_status":"single","income":{"wages":150000}}'

{
  "data": {
    "gross_income": 150000,
    "agi": 150000,
    "taxable_income": 133900,
    "ordinary_income_tax": 24734,
    "payroll_tax": { "total": 11475 },
    "total_tax": 36209,
    "effective_rate": 0.1649,
    "marginal_ordinary_rate": 0.24
  },
  "ok": true
}

compute estate-tax

Compute federal estate tax (Form 706) given a gross estate value.

Usage

entropyfa compute estate-tax --json '<JSON>'

When to Use

When a user asks about estate tax liability, exemption usage, or estate planning. Includes portability (DSUE) analysis.

Schema

Field	Description	Required
gross_estate	Total gross estate value	Yes
deductions.marital	Marital deduction	No
deductions.charitable	Charitable deduction	No
deductions.debts	Debts and expenses	No
adjusted_taxable_gifts	Lifetime taxable gifts	No
gift_tax_paid	Gift tax previously paid	No
deceased_spouse_unused_exclusion	DSUE amount (portability)	No

Example

entropyfa compute estate-tax --json '{"gross_estate":20000000,"deductions":{"marital":5000000}}'

{
  "data": {
    "gross_estate": 20000000,
    "taxable_estate": 15000000,
    "exemption_amount": 15000000,
    "net_estate_tax": 0,
    "effective_rate": 0,
    "marginal_rate": 0.4
  },
  "ok": true
}

Related: federal-tax

compute rmd

Calculate the Required Minimum Distribution for a single year. Handles owner-lifetime, inherited IRA, spouse beneficiary, and SECURE Act scenarios.

Usage

entropyfa compute rmd --json '<JSON>'

Schema

Field	Description	Required
calculation_year	Year to calculate RMD for	Yes
prior_year_end_balance	Account balance at end of prior year	Yes
account_type	traditional_ira, 401k, inherited_ira, etc.	Yes
owner_birth_date	Account owner's birth date	Yes
spouse_birth_date	Spouse's birth date	No
spouse_is_sole_beneficiary	Whether spouse is sole beneficiary	No

Related: rmd-schedule, roth-conversion

compute rmd-schedule

Project multi-year RMD schedule with balance depletion over time.

Usage

entropyfa compute rmd-schedule --json '<JSON>'

Related: rmd, roth-conversion-strategy

compute roth-conversion

Analyze the tax impact of a single-year Roth conversion.

Usage

entropyfa compute roth-conversion --json '<JSON>'

compute roth-conversion-strategy

Multi-year Roth conversion strategy with projected balances and RMD comparison.

Usage

entropyfa compute roth-conversion-strategy --json '<JSON>'

Related: roth-conversion, rmd, rmd-schedule

compute pension-comparison

Compare pension lump sum vs annuity options with tax impact, present value, and Monte Carlo analysis.

Usage

entropyfa compute pension-comparison --json '<JSON>'

Related: federal-tax, projection

compute projection

Run Monte Carlo or linear projection of portfolio balance over time. The CLI always returns the JSON envelope on stdout. The terminal dashboard is opt-in with --visual and renders to stderr in a real terminal.

Usage

entropyfa compute projection --json '<JSON>'

entropyfa compute projection --visual --json '<JSON>'

Delivery: the CLI always writes the JSON envelope to stdout and, if --visual is set, renders the dashboard separately on stderr. If --result-hook-url is set, the same JSON envelope is also POSTed as application/json.

compute goal-solver

Binary search solver to find the value of a variable that achieves a target metric.

Usage

entropyfa compute goal-solver --json '<JSON>'

Related: projection

Embedded Data and Provenance

Reference data is compiled into the binary and returned with provenance. Use entropyfa data coverage to discover the surface area and entropyfa data lookup to retrieve both the value and its verification metadata.

Trust Model

authoritative means the entry is backed by primary official sources or reviewed maintainer metadata. corroborated means multiple approved secondary sources agree. derived and placeholder remain visible so consumers can make their own trust decision.

Pipeline Reviewed vs Metadata Backed

pipeline_reviewed: true means the entry has gone through a primary agent, verifier agent, human review, and reviewed-artifact apply step. In the current public release, all 30 shipped entries are in this state.

Category	Key	Description	Parameters	Years
tax	federal_income_tax_brackets	Federal income tax brackets by filing status	filing_status	2026
tax	federal_standard_deductions	Federal standard deduction amounts by filing status	filing_status	2026
tax	federal_salt_deduction_parameters	Federal SALT deduction cap, phaseout, and floor by filing status	filing_status	2026
tax	federal_capital_gains_brackets	Federal long-term capital gains tax brackets	filing_status	2026
tax	federal_net_investment_income_tax	Net investment income tax rate and thresholds	filing_status	2026
tax	federal_payroll_tax_parameters	Social Security, Medicare, and self-employment tax parameters	filing_status	2026
tax	federal_capital_loss_limit	Annual capital loss deduction limit	filing_status	2026
tax	federal_qbi_deduction	Qualified Business Income (Section 199A) deduction parameters	filing_status	2026
tax	federal_estate_exemption	Federal estate tax exemption amount	—	2026
tax	federal_estate_brackets	Federal estate tax brackets	—	2026
tax	federal_estate_applicable_credit	Applicable credit amount against estate tax	—	2026
retirement	uniform_lifetime_table	IRS Uniform Lifetime Table (Table III) for RMDs	—	2026
retirement	single_life_table	IRS Single Life Expectancy Table (Table I)	—	2026
retirement	joint_life_table	IRS Joint Life and Last Survivor Table (Table II)	—	2026
retirement	distribution_rules	RMD distribution rules (SECURE Act / SECURE 2.0)	—	2026
social_security	benefit_taxation_thresholds	SS benefit taxation thresholds	filing_status	2026
insurance	irmaa_brackets	Medicare IRMAA surcharge brackets	filing_status, lived_with_spouse_during_year (MFS only)	2026
pension	mortality_417e	Section 417(e) mortality table for pension lump sums	—	2026

Representative Lookup Examples

This section shows three common lookup shapes: a bracket table, a compound parameter object, and a scalar estate value.

Federal Income Tax Brackets

entropyfa data lookup --category tax --key federal_income_tax_brackets --year 2026 --filing-status single

{
  "ok": true,
  "data": {
    "category": "tax",
    "key": "federal_income_tax_brackets",
    "year": 2026,
    "verification_status": "authoritative",
    "pipeline_reviewed": true,
    "source_origin": "reviewed_artifact",
    "sources": [
      {
        "authority": "Internal Revenue Service",
        "title": "Revenue Procedure 2025-32 (26 CFR 601.602)",
        "url": "https://www.irs.gov/pub/irs-drop/rp-25-32.pdf"
      }
    ],
    "value": [
      { "min": 0.0, "max": 12400.0, "rate": 0.1 },
      { "min": 12400.0, "max": 50400.0, "rate": 0.12 },
      { "...": "..." },
      { "min": 640600.0, "max": null, "rate": 0.37 }
    ]
  }
}

SALT Deduction Parameters

entropyfa data lookup --category tax --key federal_salt_deduction_parameters --year 2026 --filing-status single

{
  "ok": true,
  "data": {
    "category": "tax",
    "key": "federal_salt_deduction_parameters",
    "year": 2026,
    "verification_status": "authoritative",
    "pipeline_reviewed": true,
    "source_origin": "reviewed_artifact",
    "sources": [
      {
        "authority": "Internal Revenue Service",
        "counts_toward_status": true,
        "locator": "Corrected 2026 state and local income tax deduction amounts by filing status",
        "published_at": "2026-03-16",
        "source_class": "primary",
        "title": "Correction to State and Local Income Tax Deduction Amount in the 2026 Form 1040-ES",
        "url": "https://www.irs.gov/forms-pubs/correction-to-state-and-local-income-tax-deduction-amount-in-the-2026-form-1040-es"
      },
      {
        "authority": "Internal Revenue Service",
        "counts_toward_status": true,
        "locator": "Line 5e worksheet: 30% reduction above modified AGI threshold, but not below the statutory floor",
        "published_at": "2025-12",
        "source_class": "primary",
        "title": "2025 Instructions for Schedule A (Form 1040)",
        "url": "https://www.irs.gov/instructions/i1040sca"
      }
    ],
    "value": {
      "cap_amount": 40400.0,
      "filing_status": "single",
      "floor_amount": 10000.0,
      "phaseout_rate": 0.3,
      "phaseout_threshold": 505000.0
    }
  }
}

Federal Estate Exemption

entropyfa data lookup --category tax --key federal_estate_exemption --year 2026

{
  "ok": true,
  "data": {
    "category": "tax",
    "key": "federal_estate_exemption",
    "year": 2026,
    "verification_status": "authoritative",
    "pipeline_reviewed": true,
    "source_origin": "reviewed_artifact",
    "sources": [
      {
        "authority": "Internal Revenue Service",
        "title": "IRS releases tax inflation adjustments for tax year 2026, including amendments from the One, Big, Beautiful Bill",
        "url": "https://www.irs.gov/newsroom/irs-releases-tax-inflation-adjustments-for-tax-year-2026-including-amendments-from-the-one-big-beautiful-bill"
      }
    ],
    "value": {
      "exemption": 15000000.0
    }
  }
}

This table shows the embedded surface area. For live verification status, completeness, and source URLs, use entropyfa data lookup against the specific entry you care about.

Agent Integration

entropyfa is designed as a tool for AI agents doing financial planning. Here's how to integrate it, including the official OpenClaw skill.

The --schema Workflow

Agent calls entropyfa compute <command> --schema to learn what inputs are needed
Agent gathers required information from the user
Agent constructs JSON input and calls the command
Agent parses JSON output and reasons about results

Design Principles for Agents

--schema

on every command — agents read the schema to know what inputs to gather

data coverage

agents discover what reference data is available without hardcoding keys

JSON-in/JSON-out

structured I/O that agents parse natively

Deterministic

same input always produces the same output

No configuration

install and go, no API keys, no config files, and no outbound calls unless you explicitly use upgrade or result hooks

OpenClaw Quick Start

Install the local entropyfa CLI first, then install the official OpenClaw skill into your current workspace:

clawhub install entropyfa

The official skill is published as entropyFA Financial Planning. It provides verified financial planning data and blazing-fast, deterministic calculators for Monte Carlo projection, goal solving, Roth conversions, RMDs, income tax, estate tax, and pension analysis. Its recommended flow is:

Run entropyfa data coverage to discover available planning datasets.
Run entropyfa data lookup ... when the user needs official yearly values, trust status, or source URLs.
Run entropyfa compute <command> --schema when required inputs are missing.
Run entropyfa compute <command> --json '<JSON>' once the inputs are known.
Use compute projection --visual only when a human actually wants the terminal dashboard.

Trust note: install from the official entropyfa slug only, and review the source at github.com/Entropy-Financial-Technologies/entropyfa-cli/tree/main/integrations/openclaw/entropyfa.

Architecture

Runtime Data Flow

--json '<JSON>' / flags  →  entropyfa CLI  →  entropyfa-engine  →  stdout (JSON envelope)
                                                   \
                                                    →  optional webhook POST

Verification Pipeline

primary agent  →  verifier agent  →  human review  →  reviewed artifact
                                                           \
                                                            →  generated Rust data + metadata + snapshot

Key Properties

Local by default

Reference data and provenance are compiled into the binary; outbound calls are opt-in

Sub-millisecond

Pure computation, no I/O overhead

Single binary

No runtime dependencies

Versioned releases

Updated as reviewed reference data changes are promoted into the binary

Workspace Structure

Crate	Purpose
engine	Embedded reference data, provenance artifacts, and computation logic (usable as a Rust library)
cli	CLI that accepts JSON via --json flag, writes JSON envelopes to stdout, and can optionally POST result envelopes

Releases

entropyFA ships versioned releases as reviewed data updates are promoted into the binary. Each release bundles the current embedded dataset and provenance state at that version.

GitHub Releases: github.com/Entropy-Financial-Technologies/entropyfa-cli/releases

Upgrade: entropyfa upgrade