@fragment-dev/cli

Fragment is the Ledger API for engineers that move money. Stop wrangling payment tables, debugging balance errors and hacking together data pipelines. Start shipping the features that make a difference.

Installation

Install on macOS (Apple Silicon or Intel) or Linux x64 with glibc. Requires Node.js 18 or later on PATH:

curl -fsSL https://fragment.dev/install.sh | sh

The installer checks Node before downloading the JavaScript-only CLI archive. If Node is missing or unsupported, it exits with installation guidance. It requires no npm, Homebrew, or sudo. The launcher uses the Node executable selected during installation. Rerun the installer if you move or remove that Node executable. It installs into ~/.local/share/fragment and creates ~/.local/bin/fragment. Use the printed executable path immediately if that directory is absent from PATH. Add the directory to your shell profile for future sessions. Existing credentials and installations in other locations remain available. The installer refuses to overwrite an existing executable it does not manage.

Alternatively, install with npm:

npm install -g @fragment-dev/cli

Or install with Homebrew:

brew tap fragment-dev/tap
brew install fragment-dev/tap/fragment-cli

Run fragment update to upgrade. To pin a curl installation or roll back:

curl -fsSL https://fragment.dev/install.sh | sh -s -- --version <version>

Use --install-dir <absolute-path> and --bin-dir <absolute-path> to choose installation locations. Older releases remain in the installation directory so running commands can finish during updates.

Commands

Browser login for new users

Run fragment login --browser to sign in and select a workspace. The dashboard discovers the selected workspace's region before asking you to approve API-client creation. New users complete dashboard onboarding first. The browser and CLI must run on the same machine.

Cancelling authorization stops the CLI login and shows a confirmation in the browser. Run fragment login --browser again to retry. Use --workspace <id> to select an existing workspace directly. Credentials remain in the CLI credential directory. The browser shows a confirmation after provisioning, with a button to open the approved workspace.

Print a local schema

Run fragment print-schema --path ./fragment.jsonc to view the chart of accounts and entries as a tree and Markdown tables. Use --account <name-or-path> or --entry <name> for details; these flags cannot be combined. Account selectors accept printed template placeholders and instance IDs, such as liabilities/customer:{{customer_id}} or liabilities/customer:123. Supports JSON and JSONC files without authentication.

Simulate a scenario

Run fragment simulate-scenario --path ./fragment.jsonc --scenario "Customer payment" --step 1 to view balances after a scenario step. Steps start at 1; step 0 is not allowed. Steps beyond the scenario's last event are rejected. The output lists all scenario entries and marks the selected entry with ➡️. Entries through the selected step show account paths with account-type squares and formatted posting amounts. Later steps show only their entry names. Account balances use the chart’s box characters and nesting, with balances after each account key. Parent balances include their children. Unused scenario accounts are omitted. Accounts used by later steps remain visible at zero until they are posted to. Template instances show their actual IDs after the colon. Balances include entries through the selected step, grouped by account and currency. Balances use each currency’s precision and comma separators, enclosed in square brackets after the account. A failed entry reports its step and reason instead of printing balances. JSON and JSONC files are supported without authentication.

• fragment add-ledger-entry
• fragment api-client create
• fragment autocomplete [SHELL]
• fragment commands
• fragment create-custom-link
• fragment create-ledger
• fragment delete-custom-txs
• fragment delete-ledger
• fragment delete-schema
• fragment gen-graphql
• fragment get-schema
• fragment help [COMMAND]
• fragment init
• fragment login
• fragment migrate-ledger-entry
• fragment print-schema
• fragment query ledgerAccounts
• fragment query ledgers
• fragment query schema
• fragment query schemas
• fragment reverse-ledger-entry
• fragment simulate-scenario
• fragment start
• fragment store-schema
• fragment token
• fragment update
• fragment update-ledger-account
• fragment verify-schema
• fragment version
• fragment workspace

fragment add-ledger-entry

Add a Ledger Entry to a Ledger Account.

USAGE
  $ fragment add-ledger-entry -i <value> -l <value> -t <value> [-v] [-n <value>] [-p <value>...]

FLAGS
  -i, --ik=<value>            (required) The Idempotency Key for Ledger Entry creation.
  -l, --ledger.ik=<value>     (required) The Idempotency Key of the Ledger to post the Ledger Entry to.
  -n, --type.version=<value>  The version of the Ledger Entry type you want to post.
  -p, --param=<value>...      The parameters for your Ledger Entry. (ex: --param amount=100 --param currency=USD)
  -t, --type=<value>          (required) The `type` of Ledger Entry you want to post.
  -v, --verbose               Enable verbose mode (prints GraphQL commands).

DESCRIPTION
  Add a Ledger Entry to a Ledger Account.

  This mirrors the addLedgerEntry mutation in the GraphQL API.

  Only entries with type are allowed to be posted to a Ledger Account.


EXAMPLES
  $ fragment add-ledger-entry

FLAG DESCRIPTIONS
  -p, --param=<value>...  The parameters for your Ledger Entry. (ex: --param amount=100 --param currency=USD)

    You may specify multiple parameters by repeating the flag.

fragment api-client create

Create an API client for an integration.

USAGE
  $ fragment api-client create --workspace <value> --name <value> [--role admin|reader] [--output <value>] [--format
    json|env]

FLAGS
  --format=<option>    [default: json] Output format (applies to both stdout and --output).
                       <options: json|env>
  --name=<value>       (required) A display name for the API client.
  --output=<value>     Write the credentials to this file instead of stdout.
  --role=<option>      Role to assign the API client (defaults to your own role, capped at it).
                       <options: admin|reader>
  --workspace=<value>  (required) The Workspace id to create the API client in.

DESCRIPTION
  Create an API client for an integration.

  Authenticates in the browser and provisions a new API client for the
  given Workspace, then writes the credentials to a file or stdout. The
  authorizing user must have permission to create API clients.

EXAMPLES
  $ fragment api-client create --workspace <workspace-id> --name "Billing service" --role reader

  $ fragment api-client create --workspace <workspace-id> --name CI --output ./fragment-client.json

fragment autocomplete [SHELL]

Display autocomplete installation instructions.

USAGE
  $ fragment autocomplete [SHELL] [-r]

ARGUMENTS
  [SHELL]  (zsh|bash|powershell) Shell type

FLAGS
  -r, --refresh-cache  Refresh cache (ignores displaying instructions)

DESCRIPTION
  Display autocomplete installation instructions.

EXAMPLES
  $ fragment autocomplete

  $ fragment autocomplete bash

  $ fragment autocomplete zsh

  $ fragment autocomplete powershell

  $ fragment autocomplete --refresh-cache

See code: @oclif/plugin-autocomplete

fragment commands

List all fragment commands.

USAGE
  $ fragment commands [--json] [-c id|plugin|summary|type... | --tree] [--deprecated] [-x | ] [--hidden]
    [--no-truncate | ] [--sort id|plugin|summary|type | ]

FLAGS
  -c, --columns=<option>...  Only show provided columns (comma-separated).
                             <options: id|plugin|summary|type>
  -x, --extended             Show extra columns.
      --deprecated           Show deprecated commands.
      --hidden               Show hidden commands.
      --no-truncate          Do not truncate output.
      --sort=<option>        [default: id] Property to sort by.
                             <options: id|plugin|summary|type>
      --tree                 Show tree of commands.

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  List all fragment commands.

See code: @oclif/plugin-commands

fragment create-custom-link

Create a Custom Link

USAGE
  $ fragment create-custom-link -i <value> --name <value> [-v]

FLAGS
  -i, --ik=<value>    (required) The Idempotency Key for the Custom Link creation.
  -v, --verbose       Enable verbose mode (prints GraphQL commands).
      --name=<value>  (required) The name for the Custom Link.

DESCRIPTION
  Create a Custom Link

  This mirrors the CreateCustomLink API endpoint.
  Read https://fragment.dev/docs/sync-payments#custom-link-onboarding to learn more about Custom Links.

EXAMPLES
  $ fragment create-custom-link --ik <ik> --name <name>

fragment create-ledger

Create schematized Ledger within your Fragment workspace

USAGE
  $ fragment create-ledger -i <value> -n <value> [-v] [-s <value>]

FLAGS
  -i, --ik=<value>      (required) Idempotency key for Ledger creation
  -n, --name=<value>    (required) Ledger name (e.g. 'My First Ledger')
  -s, --schema=<value>  [default: fragment.jsonc] Path to schema file (defaults to fragment.jsonc)
  -v, --verbose         Enable verbose mode (prints GraphQL commands).

DESCRIPTION
  Create schematized Ledger within your Fragment workspace

EXAMPLES
  $ fragment create-ledger

fragment delete-custom-txs

Delete Custom Txs.

USAGE
  $ fragment delete-custom-txs --id <value>... [-v]

FLAGS
  -v, --verbose        Enable verbose mode (prints GraphQL commands).
      --id=<value>...  (required) Fragment ID of the Custom Tx to delete.

DESCRIPTION
  Delete Custom Txs.

  This mirrors the deleteCustomTxs mutation in the GraphQL API.

EXAMPLES
  $ fragment delete-custom-txs

fragment delete-ledger

Delete a Ledger.

USAGE
  $ fragment delete-ledger [-v] [-l <value>] [--ledger.id <value>]

FLAGS
  -l, --ledger.ik=<value>  The Idempotency Key of the Ledger to delete.
  -v, --verbose            Enable verbose mode (prints GraphQL commands).
      --ledger.id=<value>  The Fragment ID of the Ledger to delete.

DESCRIPTION
  Delete a Ledger.

  This mirrors the deleteLedger mutation in the GraphQL API.

EXAMPLES
  $ fragment delete-ledger

fragment delete-schema

Delete a Schema.

USAGE
  $ fragment delete-schema -k <value> [-v]

FLAGS
  -k, --key=<value>  (required) Key of the Schema to delete (e.g. template-schema).
  -v, --verbose      Enable verbose mode (prints GraphQL commands).

DESCRIPTION
  Delete a Schema.

  This mirrors the deleteSchema mutation in the GraphQL API.

EXAMPLES
  $ fragment delete-schema

fragment gen-graphql

Generate GraphQL queries from your Schema for your SDK.

USAGE
  $ fragment gen-graphql -p <value> -o <value> [--output-file-per-query] [--include-standard-queries]
    [--include-runtime-args]

FLAGS
  -o, --output=<value>            (required) The output path for the generated file(s). Must end with .graphql or .gql,
                                  unless --output-file-per-query is set. If set, the output path must be a directory.
  -p, --path=<value>              (required) The path to the schema file.
      --include-runtime-args      Include tags, groups, and conditions (when not defined in the Schema) as arguments in
                                  the generated GraphQL queries.
      --include-standard-queries  Include the set of standard queries in the output. This is required only if you are
                                  not using the Fragment SDK.
      --output-file-per-query     Output each query in a separate file instead of a single file.

DESCRIPTION
  Generate GraphQL queries from your Schema for your SDK.

  This command generates a GraphQL query for each Ledger Entry type and each Payment type in your ledger Schema.
  Use this command with Fragment SDKs to create type-safe code to update your ledger.

EXAMPLES
  Output the GraphQL queries from the schema file at <path>.

    $ fragment gen-graphql --path <path>

  Output the GraphQL queries to a specific output path.

    $ fragment gen-graphql --path <path> --output <output path>

  Output each GraphQL query in a separate file.

    $ fragment gen-graphql --path <path> --output <output path> --output-file-per-query

  Include the standard GraphQL queries and output each in a separate file.

    $ fragment gen-graphql --path <path> --output <output path> --output-file-per-query --include-standard-queries

fragment get-schema

Retrieve a schema from the API for local use

USAGE
  $ fragment get-schema [-v] [-k <value>] [--version <value>] [-o <value>]

FLAGS
  -k, --key=<value>      Key of schema (e.g. template-schema)
  -o, --output=<value>   Path to the schema file (e.g. /home/user/code/schema.jsonc). Defaults to the current directory
                         and the schema key as the file name.
  -v, --verbose          Enable verbose mode (prints GraphQL commands).
      --version=<value>  Schema version to retrieve (e.g. 2). Defaults to latest available version.

DESCRIPTION
  Retrieve a schema from the API for local use

EXAMPLES
  $ fragment get-schema

fragment help [COMMAND]

Display help for fragment.

USAGE
  $ fragment help [COMMAND...] [-n]

ARGUMENTS
  [COMMAND...]  Command to show help for.

FLAGS
  -n, --nested-commands  Include all nested commands in the output.

DESCRIPTION
  Display help for fragment.

See code: @oclif/plugin-help

fragment init

Initialize an example chart of accounts locally

USAGE
  $ fragment init [-f <value>]

FLAGS
  -f, --file=<value>  [default: fragment.jsonc] Path to write initial schema to

DESCRIPTION
  Initialize an example chart of accounts locally

EXAMPLES
  $ fragment init

fragment login

Authenticate with FRAGMENT.

USAGE
  $ fragment login [--browser] [--workspace <value>] [--client-id <value>] [--client-secret <value>]
    [--api-url <value>] [--oauth-url <value>] [--oauth-scope <value>] [--test]

FLAGS
  --api-url=<value>        The API URL for your FRAGMENT Workspace (ex: https://api.us-west-2.fragment.dev/graphql)
  --browser                Authenticate in the browser and provision an API client automatically.
  --client-id=<value>      The API Client ID for your FRAGMENT Workspace.
  --client-secret=<value>  The API Client Secret for your FRAGMENT Workspace
  --oauth-scope=<value>    The OAuth Scope for your auth token (ex: https://api.us-west-2.fragment.dev/*)
  --oauth-url=<value>      The OAuth URL from which to retrieve your auth token (ex:
                           https://auth.fragment.dev/oauth2/token)
  --test                   If set, tests stored credentials only
  --workspace=<value>      The Workspace id. Omit to select a workspace after browser login.

DESCRIPTION
  Authenticate with FRAGMENT.

  Authentication is scoped to one FRAGMENT Workspace.
  If you want to authenticate with another Workspace, you must create another API Client and follow the authentication
  flow again.
  Credentials will be written to ~/.fragment/auth.json.

EXAMPLES
  $ fragment login

  $ fragment login --browser --workspace <workspace-id>

  $ fragment login --client-id <client-id> --client-secret <client-secret> --api-url <api-url> --oauth-url <oauth-url>

fragment migrate-ledger-entry

Migrate a Ledger Entry to a new type and version.

USAGE
  $ fragment migrate-ledger-entry -e <value> -l <value> -t <value> [-v] [-n <value>] [-p <value>...]

FLAGS
  -e, --entry.id=<value>                (required) The ID of the Ledger Entry to migrate.
  -l, --ledger.ik=<value>               (required) The Idempotency Key of the Ledger containing the entry.
  -n, --new.entry.type.version=<value>  The new version of the Ledger Entry type.
  -p, --param=<value>...                The parameters for the new Ledger Entry. (ex: --param amount=100 --param
                                        currency=USD)
  -t, --new.entry.type=<value>          (required) The new type for the migrated Ledger Entry.
  -v, --verbose                         Enable verbose mode (prints GraphQL commands).

DESCRIPTION
  Migrate a Ledger Entry to a new type and version.

  This mirrors the migrateLedgerEntry mutation in the GraphQL API.

  Migrates an existing Ledger Entry to a new type and version with new parameters.


EXAMPLES
  $ fragment migrate-ledger-entry

FLAG DESCRIPTIONS
  -p, --param=<value>...  The parameters for the new Ledger Entry. (ex: --param amount=100 --param currency=USD)

    You may specify multiple parameters by repeating the flag.

fragment print-schema

Pretty-print the chart of accounts and entries in a local schema

USAGE
  $ fragment print-schema [-p <value>] [--account <value> | --entry <value>]

FLAGS
  -p, --path=<value>     [default: fragment/fragment.json] Path to a schema JSON or JSONC file
      --account=<value>  Show one account by name, key, or full path
      --entry=<value>    Show an entry type and its versions, including posting lines

DESCRIPTION
  Pretty-print the chart of accounts and entries in a local schema

EXAMPLES
  $ fragment print-schema --path ./fragment.jsonc

  $ fragment print-schema --path ./fragment.jsonc --account assets/cash

  $ fragment print-schema --account "Cash"

  $ fragment print-schema --entry carrier_paid

fragment query ledgerAccounts

Get accounts for ledger within your workspace by ID

USAGE
  $ fragment query ledgerAccounts -l <value> [-v] [--first <value>] [--after <value>]

FLAGS
  -l, --ledger=<value>  (required) Ledger ID to retrieve accounts for
  -v, --verbose         Enable verbose mode (prints GraphQL commands).
      --after=<value>   Cursor to paginate through ledger accounts
      --first=<value>   Number of ledger accounts to retrieve in each page

DESCRIPTION
  Get accounts for ledger within your workspace by ID

EXAMPLES
  $ fragment query ledgerAccounts

fragment query ledgers

List all ledgers in your workspace

USAGE
  $ fragment query ledgers [-v]

FLAGS
  -v, --verbose  Enable verbose mode (prints GraphQL commands).

DESCRIPTION
  List all ledgers in your workspace

EXAMPLES
  $ fragment query ledgers

fragment query schema

Get schema from your workspace by key

USAGE
  $ fragment query schema -k <value> [-v] [--version <value>]

FLAGS
  -k, --key=<value>      (required) Key of schema (e.g. template-schema)
  -v, --verbose          Enable verbose mode (prints GraphQL commands).
      --version=<value>  Schema version to retrieve (e.g. 2). Defaults to latest available version.

DESCRIPTION
  Get schema from your workspace by key

EXAMPLES
  $ fragment query schema

fragment query schemas

List all schemas in your workspace

USAGE
  $ fragment query schemas [-v]

FLAGS
  -v, --verbose  Enable verbose mode (prints GraphQL commands).

DESCRIPTION
  List all schemas in your workspace

EXAMPLES
  $ fragment query schemas

fragment reverse-ledger-entry

Reverse a Ledger Entry.

USAGE
  $ fragment reverse-ledger-entry --id <value> [-v]

FLAGS
  -v, --verbose     Enable verbose mode (prints GraphQL commands).
      --id=<value>  (required) Fragment ID of the Ledger Entry to reverse.

DESCRIPTION
  Reverse a Ledger Entry.

  This mirrors the reverseLedgerEntry mutation in the GraphQL API.

EXAMPLES
  $ fragment reverse-ledger-entry

fragment simulate-scenario

Simulate account balances after a scenario step

USAGE
  $ fragment simulate-scenario --scenario <value> --step <value> [-p <value>]

FLAGS
  -p, --path=<value>      [default: fragment/fragment.json] Path to a schema JSON or JSONC file
      --scenario=<value>  (required) Scenario name from the schema
      --step=<value>      (required) Step to include (1-based). Step 0 is not allowed

DESCRIPTION
  Simulate account balances after a scenario step

EXAMPLES
  $ fragment simulate-scenario --path ./fragment.jsonc --scenario "Customer payment" --step 1

fragment start

Develop your chart of accounts locally

USAGE
  $ fragment start [-p <value>] [-f <value>] [--websocket-port <value>]

FLAGS
  -f, --file=<value>            [default: fragment.jsonc] Path for schema JSON file. Default to fragment.jsonc
  -p, --port=<value>            [default: 9410] Port for schema visualizer to run on
      --websocket-port=<value>  Port for the websocket to live on that syncs changes between the CLI and visualizer

DESCRIPTION
  Develop your chart of accounts locally

EXAMPLES
  $ fragment start --file ./my-fragment-schema.json

fragment store-schema

Store schema within your Fragment workspace

USAGE
  $ fragment store-schema [-v] [-p <value>]

FLAGS
  -p, --path=<value>  [default: fragment.jsonc] Path to schema file (e.g. fragment.jsonc)
  -v, --verbose       Enable verbose mode (prints GraphQL commands).

DESCRIPTION
  Store schema within your Fragment workspace

EXAMPLES
  $ fragment store-schema

fragment token

Get a FRAGMENT Authentication Token.

USAGE
  $ fragment token [-v]

FLAGS
  -v, --verbose  Enable verbose mode (prints GraphQL commands).

EXAMPLES
  $ fragment token

fragment update

Update the FRAGMENT CLI

USAGE
  $ fragment update [-y] [--dry-run]

FLAGS
  -y, --yes
  --dry-run

DESCRIPTION
  Update the FRAGMENT CLI

EXAMPLES
  $ fragment update

fragment update-ledger-account

Update a Ledger Account within your Fragment Ledger.

USAGE
  $ fragment update-ledger-account --update.name <value> [-v] [-p <value> | --ledgerAccount.id <value>] [-l <value>]
    [--ledger.id <value>]

FLAGS
  -l, --ledger.ik=<value>           The Idempotency Key of the Ledger the Ledger Account is in.
  -p, --ledgerAccount.path=<value>  The unique path of the Ledger Account.
  -v, --verbose                     Enable verbose mode (prints GraphQL commands).
      --ledger.id=<value>           The Fragment ID of the Ledger the Ledger Account is in.
      --ledgerAccount.id=<value>    The Fragment ID of the Ledger Account.
      --update.name=<value>         (required)

DESCRIPTION
  Update a Ledger Account within your Fragment Ledger.

  This mirrors the updateLedgerAccount mutation in the GraphQL API.

EXAMPLES
  $ fragment update-ledger-account

fragment verify-schema

Verify that a schema file follows the Fragment JSON schema format

USAGE
  $ fragment verify-schema [-p <value>] [-v] [-j] [-a <value>]

FLAGS
  -a, --against=<value>  Path to a previous version of the schema to check backwards compatibility against (e.g. the
                         output of `fragment get-schema`)
  -j, --json             Output validation results as JSON for programmatic use
  -p, --path=<value>     [default: fragment/fragment.json] Path to schema file (e.g. my-schema.jsonc)
  -v, --verbose          Show detailed validation output

DESCRIPTION
  Verify that a schema file follows the Fragment JSON schema format

EXAMPLES
  $ fragment verify-schema

  $ fragment verify-schema --path ./my-schema.jsonc

  $ fragment verify-schema -p fragment/fragment.json --verbose

  $ fragment verify-schema --path ./my-schema.jsonc --json

  Check that the schema is backwards-compatible with the deployed schema.

    $ fragment get-schema --key my-schema --output deployed-schema.jsonc && fragment verify-schema --path \
      my-schema.jsonc --against deployed-schema.jsonc

  Check that the schema is backwards-compatible with its copy on the main branch.

    $ git show origin/main:my-schema.jsonc > base-schema.jsonc && fragment verify-schema --path my-schema.jsonc \
      --against base-schema.jsonc

fragment version

Print the installed FRAGMENT CLI version.

USAGE
  $ fragment version

DESCRIPTION
  Print the installed FRAGMENT CLI version.

EXAMPLES
  $ fragment version

fragment workspace

Get the details of the workspace this CLI is authenticated to

USAGE
  $ fragment workspace [-v]

FLAGS
  -v, --verbose  Enable verbose mode (prints GraphQL commands).

DESCRIPTION
  Get the details of the workspace this CLI is authenticated to

EXAMPLES
  $ fragment workspace