Ledger Cli Commands | Fragment

E CLI#

Use the CLI to:

Generate GraphQL queries specific to your Schema
Embed the CLI within your CI/CD process
Quickly store a Schema, create a Ledger, and start posting Ledger Entries

Install the CLI via NPM:

npm install -g @fragment-dev/cli

or via Homebrew:

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

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.

Usage

fragment login \
  [--api-url=<api-url>] \
  [--client-id=<client-id>] \
  [--client-secret=<client-secret>] \
  [--oauth-scope=<oauth-scope>] \
  [--oauth-url=<oauth-url>] \
  [--test]

Optionally, run fragment login and the CLI will prompt you for the credentials.

Flags


--browser	Authenticate in the browser and provision an API client automatically
--workspace=<workspace>	The Workspace id to authenticate against (required with --browser)
--mcp-url=<mcp-url>	The Workspace MCP server origin, e.g. `https://mcp.us-west-2.fragment.dev` (used with --browser)
--api-url=<api-url>	The API URL for your FRAGMENT Workspace
--client-id=<client-id>	The API Client ID
--client-secret=<client-secret>	The API Client Secret
--oauth-scope=<oauth-scope>	The OAuth Scope for your auth token
--oauth-url=<oauth-url>	The OAuth URL from which to retrieve the auth token
--test	If set, tests stored credentials

Example

fragment login \
  --api-url="<api-url>" \
  --client-id="<client-id>" \
  --client-secret="<client-secret>" \
  --oauth-scope="<oauth-scope>" \
  --oauth-url="<oauth-url>"

Or authenticate in the browser and let the CLI provision an API client for you:

fragment login --browser --workspace="<workspace-id>"

To test the stored credentials, run:

fragment login --test

Authenticate in the browser and provision a new API client for an integration, then write the credentials to a file or stdout. The authorizing user must have permission to create API clients.

Usage

fragment api-client create \
  --workspace=<workspace> \
  --name=<name> \
  [--role=admin|reader] \
  [--mcp-url=<mcp-url>] \
  [--output=<path>] \
  [--format=json|env]

Flags


--workspace=<workspace>	The Workspace id to create the API client in
--name=<name>	A display name for the API client
--role=admin\|reader	Role to assign the API client (defaults to your own role, capped at it)
--mcp-url=<mcp-url>	The Workspace MCP server origin (falls back to FRAGMENT_MCP_URL)
--output=<path>	Write the credentials to this file instead of stdout
--format=json\|env	Output format (applies to both stdout and --output)

Example

fragment api-client create \
  --workspace="<workspace-id>" \
  --name="Billing service" \
  --role="reader"

Store a Schema within your FRAGMENT workspace.

Usage

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

Flags


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

Example

fragment store-schema \
  -p your-fragment-schema.jsonc

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

By default, this command looks for a file named fragment.json in the fragment/ directory. You can specify a different path using the --path flag.

Usage

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

Flags


-p, --path=<value>	[default: fragment/fragment.json] Path to schema file (e.g. fragment/fragment.json)
-v, --verbose	Show detailed validation output
-j, --json	Output validation results as JSON for programmatic use

Examples

# Verify fragment/fragment.json (default behavior)
fragment verify-schema

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

fragment verify-schema \
  -p fragment.jsonc \
  --verbose

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

Create a Ledger within your FRAGMENT workspace.

Usage

fragment create-ledger \
  --ik=<ledger-ik> \
  --name=<ledger-name> \
  --schema=<schema-file>

Flags


-i, --ik=<ledger-ik>	Idempotency key for `createLedger`
-n, --name=<ledger-name>	Ledger name
-s, --schema=<schema-key>	[default: fragment.jsonc] Path to the schema JSON file.
-v, --verbose	Enable verbose mode (prints GraphQL commands)

Example

fragment create-ledger \
  --ik=test-ledger \
  --name="Test Ledger" \
  --schema=your-fragment-schema.jsonc

Retrieve a Schema from the API for local use.

Usage

fragment get-schema \
  [--key=<schema-key>] \
  [--version=<version>] \
  [--output=<output-file>] \
  [-v]

Flags


-k, --key=<schema-key>	(Optional) Key of the Schema (e.g. template-schema). If not provided, you'll be prompted to choose a Schema.
-o, --output=<output-file>	Path to the JSONC schema file. Defaults to the schema key in the current directory.
--version=<version>	Schema version to retrieve. Defaults to the latest version.
-v, --verbose	Enable verbose mode (prints GraphQL commands)

Example

To choose the Schema from a list, run:

fragment get-schema

If providing the Schema key, run:

Providing a Schema key

fragment get-schema \
  --key=test-schema

Post a Ledger Entry to your FRAGMENT Ledger.

Usage

fragment add-ledger-entry \
  --ik=<add-ledger-entry-ik> \
  --ledger.ik=<ledger-ik> \
  --type=<entry-type> \
  [--param=<parameter-value>] \
  [-v]

Flags


-i, --ik=<add-ledger-entry-ik>	Idempotency key for `addLedgerEntry`
-l, --ledger.ik=<ledger-ik>	Idempotency Key of the Ledger to post the Ledger Entry to
-t, --type=<entry-type>	The `type` of Ledger Entry you want to post
-p, --param=<value>...	The parameters for your Ledger Entry. You may specify multiple parameters by repeating the flag. (ex: --param amount=100 --param currency=USD)
-v, --verbose	Enable verbose mode (prints GraphQL commands)

Example

fragment add-ledger-entry \
  --ik=your-entry-ik \
  --ledger.ik=your-ledger-ik \
  --type=user_funds_account \
  --param='user_id="testing-user"' \
  --param='funding_amount="200"'

Create a Custom Link.

Usage

fragment create-custom-link \
  --ik=<custom-link-ik> \
  --name=<custom-link-name>

Flags


-i, --ik=<custom-link-ik>	The Idempotency Key for Custom Link creation
--name=<custom-link-name>	The name for the Custom Link

Examples

fragment create-custom-link \
  --ik="example-custom-link" \
  --name="Example Custom Link"

Delete Custom Txs.

Usage

fragment delete-custom-txs \
  --id=<custom-tx-id> \
  --id=<custom-tx-id-2>

Flags


--id=<custom-tx-id>	FRAGMENT ID of the Custom Tx to delete

Examples

fragment delete-custom-txs \
  --id="fragment-custom-tx-id"

Delete a Ledger.

Usage

fragment delete-ledger \
  --ledger.ik=<ledger-ik>

Flags


-l, --ledger.ik=<ledger-ik>	The Idempotency Key of the Ledger to delete
--ledger.id=<ledger-id>	The FRAGMENT ID of the Ledger to delete

Examples

fragment delete-ledger \
  --ledger.ik=fragment-ledger-ik

Delete a FRAGMENT Schema.

Usage

fragment delete-schema \
  --key=<schema-key>

Flags


-k, --key=<schema-key>	Key of the Schema to delete (e.g. template-schema)

Examples

fragment delete-schema \
  --key="template-schema"

Generate GraphQL queries to post Ledger Entries for a given Schema.

The generated GraphQL queries can be used to generate SDK code specific to your Schema. Read Embed in CI to learn more.

Usage

fragment gen-graphql \
  --path=<path-to-schema.jsonc> \
  --output=<output-filename.graphql>

Flags


-o, --output=<output-filename>	The path for the generated file. Must end with `.graphql` or `.gql`
-p, --path=<schema-file-path>	The path to your Schema file
--output-file-per-query	Output a folder of queries, instead of a single file
--include-standard-queries	Include the set of standard GraphQL queries in the output. This is required only if you are not using the FRAGMENT SDKs
--include-runtime-args	Include tags, groups, and conditions (when not defined in the Schema) as arguments in the generated GraphQL queries

Example

fragment gen-graphql \
  --path=your-fragment-schema.jsonc \
  --output=queries.graphql

fragment gen-graphql \
  --path=your-fragment-schema.jsonc \
  --output=generated/queries \
  --output-file-per-query

Migrate a Ledger Entry to a new type and version.

Usage

fragment migrate-ledger-entry \
  --entry.id=<entry-id> \
  --ledger.ik=<ledger-ik> \
  --new.entry.type=<new-entry-type> \
  [--new.entry.type.version=<new-entry-type-version>] \
  [--param <key>=<value>]... \
  [-v]

Flags


-e, --entry.id=<entry-id>	The FRAGMENT ID of the Ledger Entry to migrate
-l, --ledger.ik=<ledger-ik>	The Idempotency Key of the Ledger containing the entry
-t, --new.entry.type=<new-entry-type>	The new type for the migrated Ledger Entry
-n, --new.entry.type.version=<new-entry-type-version>	The new version of the Ledger Entry type
-p, --param=<key>=<value>	The parameters for the new Ledger Entry. You may specify multiple parameters by repeating the flag
-v, --verbose	Enable verbose mode (prints GraphQL commands)

Example

fragment migrate-ledger-entry \
  --entry.id=test-entry-id \
  --ledger.ik=test-ledger-ik \
  --new.entry.type=new-entry-type \
  --new.entry.type.version=2 \
  --param amount=100 \
  --param currency=USD

Reverse a Ledger Entry.

Usage

fragment reverse-ledger-entry \
  --id=<ledger-entry-id>

Flags


--id=<ledger-entry-id>	The FRAGMENT ID of the Ledger Entry to reverse

Example

fragment reverse-ledger-entry \
  --id=test-ledger-entry-id

Update the FRAGMENT CLI.

Usage

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

Flags


-y, --yes	Update without being prompted
--dry-run	Run the update process without updating the CLI

Example

fragment update -y

Get a FRAGMENT Authentication Token.

This will print your auth token to standard output (stdout).

Usage

fragment token

Display help prompt for the CLI.

Usage

fragment help [COMMANDS]

Flags


COMMANDS...	The Command (or Commands) to show help for. Ex: `store-schema`

Example

fragment help store-schema

Get the details of the Workspace this CLI is authenticated to.

Usage

fragment workspace