# CLI

Source: https://fragment.dev/api-reference/ledger-cli-commands

[Documentation index](https://fragment.dev/llms.txt)

<a id="ledger-cli-commands"></a>

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

<a id="browser-login"></a>

## Browser login

Run `fragment login --browser` to authorize the CLI through the hosted dashboard.
Select a workspace after login; the CLI discovers its regional authorization service automatically.
New users complete automatic workspace onboarding first.
Use `--workspace <id>` to select an existing workspace directly.
The CLI and browser 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.
After authorization, the browser confirms the connection and offers a button to open the workspace dashboard.
An MCP connection in your agent is not required.

<a id="choose-a-setup-method"></a>

## Choose a setup method

To set up the CLI on your own machine, [connect your coding agent to the MCP server](https://fragment.dev/markdown/api-reference/mcp.md#get-started) and ask it to set up the CLI. The coding agent installs the CLI and starts a login for you to approve in the browser.

To set up the CLI in CI, or in any environment where nobody can complete an interactive login, follow the manual steps below to install the CLI, create an API Client, and log in with its credentials.

<a id="install"></a>

## Install
Install the CLI via NPM:

```plaintext
npm install -g @fragment-dev/cli
```

or via [Homebrew](https://brew.sh/):
```plaintext
brew tap fragment-dev/tap &&\
  brew install fragment-dev/tap/fragment-cli
```

<a id="version"></a>

## version

Print the installed Fragment CLI version.

This prints the version to standard output (stdout). If a newer release is available, run `fragment update` to upgrade.

###### Usage

```plaintext
fragment version
```

<a id="login"></a>

## login

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

```plaintext
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. Omit to select a workspace after browser login |
| --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

```bash
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:

```bash
fragment login --browser --workspace="\<workspace-id\>"
```

To test the stored credentials, run:

```bash
fragment login --test
```

<a id="api-client-create"></a>

## api-client create

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

```plaintext
fragment api-client create \
  --workspace=<workspace> \
  --name=<name> \
  [--role=admin|reader] \
  [--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) |
| --output=\<path\> | Write the credentials to this file instead of stdout |
| --format=json\|env | Output format (applies to both stdout and --output) |

###### Example

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

<a id="store-schema"></a>

## store-schema

Store a Schema within your Fragment workspace.

###### Usage

```plaintext
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

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

<a id="verify-schema"></a>

## verify-schema

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

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

###### 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 |
| -a, --against=\<value\> | Path to a previous version of the schema to check backwards compatibility against |

###### Examples

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

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

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

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

```bash
# Check backwards compatibility 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
```

```bash
# Check backwards compatibility with the main branch
git show origin/main:my-schema.jsonc > base-schema.jsonc &&\
fragment verify-schema \
  --path my-schema.jsonc \
  --against base-schema.jsonc
```

`--against` applies the same backwards-compatibility rules as `store-schema`. It always enforces them, even for a Schema with no Ledgers. To run the check on pull requests, see [Embed in CI](https://fragment.dev/markdown/guides/embed-in-ci.md#check-backwards-compatibility).

<a id="create-ledger"></a>

## create-ledger

Create a Ledger within your Fragment workspace.

###### Usage

```plaintext
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

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

<a id="get-schema"></a>

## get-schema

Retrieve a Schema from the API for local use.

###### Usage

```plaintext
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:

```bash
fragment get-schema
```

If providing the Schema key, run:

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

<a id="add-ledger-entry"></a>

## add-ledger-entry

Post a Ledger Entry to your Fragment Ledger.

###### Usage

```plaintext
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

```bash
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"'
```

<a id="create-custom-link"></a>

## create-custom-link

Create a [Custom Link](https://fragment.dev/markdown/guides/sync-payments.md#custom-link).

###### Usage

```plaintext
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

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

<a id="delete-custom-txs"></a>

## delete-custom-txs

Delete [Custom Txs](https://fragment.dev/markdown/guides/sync-payments.md#custom-link-sync-txs).

###### Usage

```plaintext
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

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

<a id="delete-ledger"></a>

## delete-ledger

Delete a Ledger.

###### Usage

```plaintext
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

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

<a id="delete-schema"></a>

## delete-schema

Delete a Fragment Schema.

###### Usage

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

###### Flags

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

###### Examples

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

<a id="gen-graphql"></a>

## gen-graphql

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

You get one mutation per Ledger Entry Type, and one per Payment Type. A Payment Type's mutation takes the parameters that Type references, less the ones Fragment fills in when the Payment settles.

The generated GraphQL queries can be used to generate SDK code specific to your Schema. Read [Embed in CI](https://fragment.dev/markdown/guides/embed-in-ci.md) to learn more.

###### Usage

```plaintext
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

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

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

<a id="migrate-ledger-entry"></a>

## migrate-ledger-entry

Migrate a Ledger Entry to a new type and version.

###### Usage

```plaintext
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

```bash
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
```

<a id="reverse-ledger-entry"></a>

## reverse-ledger-entry

Reverse a Ledger Entry.

###### Usage

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

###### Flags

|    |    |
| -- | -- |
| --id=\<ledger-entry-id\> | The Fragment ID of the Ledger Entry to reverse |

###### Example

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

<a id="update"></a>

## update

Update the Fragment CLI.

###### Usage

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

###### Flags

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

###### Example

```bash
fragment update -y
```

The CLI checks for a newer release on each command and warns if you're out of date. Set `FRAGMENT_SKIP_AUTO_UPDATE=true` to skip this check:

```bash
FRAGMENT_SKIP_AUTO_UPDATE=true \
  fragment store-schema --path ./schema.jsonc
```

<a id="token"></a>

## token

Get a Fragment Authentication Token.

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

###### Usage

```plaintext
fragment token
```

<a id="help"></a>

## help

Display help prompt for the CLI.

###### Usage

```plaintext
fragment help [COMMANDS]
```

###### Flags

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

###### Example

```plaintext
fragment help store-schema
```

<a id="workspace"></a>

## workspace

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

###### Usage

```plaintext
fragment workspace
```