curl -fsSL https://driftledger.fatclaw.com/install.sh | bashOne command installs the public package, then prints the next auth and agent setup commands.
Install once with bash, then let Codex, Claude Code, OpenClaw, CI jobs, and local scripts upload ledgers, create checks, run rules, inspect incidents, and verify alert delivery through JSON-first commands.
Use the hosted install when the npm package is live. During local validation, install from the local checkout and point the CLI at your backend.
Use once the public npm package and install script are published.
curl -fsSL https://driftledger.fatclaw.com/install.sh | bash
dl config set --api-url https://driftledger.fatclaw.com
dl auth login --email you@example.com --password "<password>"Use the sibling dl-agent checkout while validating the CLI against local frontend/backend work.
npm install -g ../dl-agent/packages/cli
dl config set --api-url http://localhost:8088
dl doctorUse environment variables when the agent cannot write ~/.driftledger/config.json.
export DRIFTLEDGER_API_URL="https://driftledger.fatclaw.com"
export DRIFTLEDGER_TOKEN="<jwt>"
export DRIFTLEDGER_WORKSPACE_ID="Default"Agents should follow this exact order. If no workspace is specified, dl uses Default. Each step produces JSON or a reviewed body file that the next step can reuse.
Make sure the dl binary, API URL, token, and workspace context are visible before modifying data.
command -v dl >/dev/null || npm install -g @driftledger/cli
dl doctor
dl auth verifyDefault is the implicit workspace for metadata, data, models, rules, RuleForest, runs, incidents, and alerts.
dl workspace list
# Optional override for a non-default workspace:
dl workspace activate --workspace <spId>Write the project instruction file, then install optional DriftLedger skills into the local agent skill directory.
dl agent init codex --out AGENTS.md
mkdir -p ~/.codex/skills
cp -R skills/driftledger-cli ~/.codex/skills/
cp -R skills/driftledger-incident-review ~/.codex/skills/Upload assembled JSONL directly when joins already exist, or upload raw CSV tables and run assembly first.
dl dataset create-assembled --display-name refund-payment-fund
dl dataset upload-assembled --dataset <datasetId> --file assembled.jsonl
# Or: metadata -> source binding -> raw CSV upload -> assemblyDefine the table relationships and parent object that rules attach to.
dl check-model create --body-file check-model.json
dl check-model deploy --id <riskModelId>
dl check-model enable --id <riskModelId>Mine candidate rules from samples or add a manually reviewed rule payload. Manual ruleType values must come from the algorithm rule type list.
dl infer-task submit --body-file infer-task.json
dl infer-task progress --task <inferTaskId>
dl rule types
dl rule add --body-file rule.jsonCompile workspace rules before execution so runs load the rule tree first.
dl rule-forest build
dl rule-forest statusCreate email or webhook channels before production runs and send a test alert.
dl alerts upsert --body-file alert-email-channel.json
dl alerts test --channel <channelId>Submit execution, inspect result indexes and incidents, then verify alert delivery logs.
dl run submit --body-file run.json
dl run run --task <taskId>
dl incidents task --task <taskId>
dl alerts deliveries --task <taskId>Generate a short instruction block for the agent runtime. Secrets stay in environment variables, not in chats or repository docs.
Writes a project-local AGENTS.md block with the DriftLedger command contract.
dl agent init codex --out AGENTS.mdWrites a CLAUDE.md block for shell-first reconciliation workflows.
dl agent init claude --out CLAUDE.mdWrites an OPENCLAW.md block for OpenClaw agents and compatible runners.
dl agent init openclaw --out OPENCLAW.mdPrints a portable Markdown contract when the runtime has no named preset yet.
dl agent init genericEvery command returns JSON. Pass complex payloads through --body-file so agents can create, review, and retry files deterministically.
Check runtime state, persist API settings, log in, and select the workspace scope used by later commands.
Shows API URL, token presence, workspace, and config path.
dl doctor
dl version
dl config getLogin captures the AUTH_TOKEN cookie into local config unless --no-save is used.
dl config set --api-url https://driftledger.fatclaw.com --workspace <spId>
dl auth login --email you@example.com --password "<password>"
dl auth verify
dl auth refreshWorkspaces isolate metadata, datasets, models, rules, runs, and incidents.
dl workspace list
dl workspace create --name "Demo workspace"
dl workspace get --workspace <spId>
dl workspace activate --workspace <spId>Define table metadata, bind source columns, upload raw exports, or skip assembly by uploading a joined ledger.
Create a meta table with fields, then bind uploaded source columns to that schema. Field types are optional; use algorithm types only when constraining inference.
dl metadata col-types
dl metadata upsert --workspace <spId> --body-file meta.json
dl metadata tables --workspace <spId>
dl metadata fields --workspace <spId> --table <metaTableId>
dl data-source upsert --workspace <spId> --display-name "Orders export" --type CSV_UPLOAD
dl source-binding upsert --workspace <spId> --body-file binding.jsonUse when DriftLedger should preserve source-table identity before assembly or checking.
dl dataset create-raw --workspace <spId> --display-name orders --binding-id <bindingId>
dl dataset upload --workspace <spId> --dataset <datasetId> --file orders.csv
dl dataset list --workspace <spId>
dl dataset detail --workspace <spId> --dataset <datasetId>Turn raw table datasets into assembled records for training and execution.
dl assembly submit --workspace <spId> --body-file assembly.json
dl assembly run --workspace <spId> --task <assemblyTaskId>Use when your agent or data job already produced the joined ledger as JSONL or CSV.
dl dataset create-assembled --workspace <spId> --display-name assembled-ledger
dl dataset upload-assembled --workspace <spId> --dataset <datasetId> --file assembled.jsonl
dl dataset download --workspace <spId> --dataset <datasetId> --artifact <artifactId> --out evidence.jsonlCreate a business reconciliation model, add human-reviewed rules, then deploy or enable the model for execution.
A model groups related invariants such as payment-to-access or refund-to-settlement checks.
dl check-model create --workspace <spId> --body-file check-model.json
dl check-model update --workspace <spId> --body-file check-model.json
dl check-model deploy --workspace <spId> --id <riskModelId>
dl check-model enable --workspace <spId> --id <riskModelId>
dl check-model list --workspace <spId> --code <modelCode>Rules can be added from AI suggestions, manual review, or migration scripts. Query algorithm rule types before writing manual rule payloads.
dl rule types
dl rule add --workspace <spId> --body-file rule.json
dl rule list --workspace <spId> --page 0 --page-size 20
dl rule get --workspace <spId> --id <ruleId>
dl rule enable --workspace <spId> --id <ruleId>
dl rule disable --workspace <spId> --id <ruleId>Build the workspace RuleForest after rule changes, or let the backend scheduler rebuild stale forests.
dl api request POST /api/v1/rule-forest/build/<spId>
dl api request GET /api/v1/rule-forest/status/<spId>Submit a run, execute it, inspect warning indexes, fetch incidents, and confirm alert delivery.
Submit first to create a task record, then run it when the backend runner is available.
dl run submit --workspace <spId> --body-file run.json
dl run run --workspace <spId> --task <taskId>
dl run indexes --workspace <spId> --task <taskId>Use these after a run to let an agent summarize business drift with evidence rows.
dl incidents list --workspace <spId>
dl incidents task --workspace <spId> --task <taskId>
dl incidents get --workspace <spId> --incident <incidentId>
dl incidents actions --workspace <spId> --incident <incidentId>Notify users through email or webhook, then verify test sends and incident notifications.
dl alerts upsert --workspace <spId> --body-file alert-email-channel.json
dl alerts list --workspace <spId>
dl alerts test --workspace <spId> --channel <channelId>
dl alerts deliveries --workspace <spId> --task <taskId>Fallback for a new backend endpoint before a high-level CLI alias exists.
dl api request GET /api/v1/token/verify
dl api request POST /api/v1/custom/path --body '{"dryRun":true}'These examples are short enough for an agent to run, inspect JSON output, save IDs, and continue without manual browser steps.
Give Codex an AGENTS.md contract, verify auth, and keep credentials out of the repository.
npm install -g @driftledger/cli
export DRIFTLEDGER_TOKEN="<jwt>"
dl config set --api-url https://driftledger.fatclaw.com --workspace <spId>
dl agent init codex --out AGENTS.md
dl doctorCreate metadata, bind CSV columns, upload the file, then let the agent capture dataset IDs from JSON output.
dl metadata col-types
dl metadata upsert --workspace <spId> --body-file meta.json
dl data-source upsert --workspace <spId> --display-name "Orders CSV" --type CSV_UPLOAD
dl source-binding upsert --workspace <spId> --body-file binding.json
dl dataset create-raw --workspace <spId> --display-name orders --binding-id <bindingId>
dl dataset upload --workspace <spId> --dataset <datasetId> --file orders.csv
dl assembly submit --workspace <spId> --body-file assembly.json
dl assembly run --workspace <spId> --task <assemblyTaskId>Skip source assembly when another job already produced the joined payment/order/settlement rows.
dl dataset create-assembled --workspace <spId> --display-name payment-ledger
dl dataset upload-assembled --workspace <spId> --dataset <datasetId> --file payment-ledger.jsonl
dl check-model create --workspace <spId> --body-file check-model.json
dl rule types
dl rule add --workspace <spId> --body-file rule.json
dl alerts upsert --workspace <spId> --body-file alert-email-channel.json
dl run submit --workspace <spId> --body-file run.json
dl run run --workspace <spId> --task <taskId>
dl incidents task --workspace <spId> --task <taskId>
dl alerts deliveries --workspace <spId> --task <taskId>Avoid local config writes and make every output parseable by the next automation step.
export DRIFTLEDGER_API_URL="https://driftledger.fatclaw.com"
export DRIFTLEDGER_TOKEN="${DRIFTLEDGER_CI_TOKEN}"
export DRIFTLEDGER_WORKSPACE_ID="sp_prod"
dl doctor
dl auth verify
dl api request GET /api/v1/token/verifyThe companion dl-agent repository includes a sanitized refund/payment/fund consistency scenario that agents can use for training, validation, and incident smoke tests.
Use the named scenario folder instead of a generic demo name when referencing public assets.
samples/refund-payment-fund-consistencyTrain from clean assembled records, validate with both clean and controlled-anomaly records.
datasets/train.jsonl
datasets/test.jsonl
datasets/test-with-anomaly.jsonlThe model keeps join structure and rule context while replacing accounts, orders, payment IDs, names, and long identifiers with demo tokens.
models/demo_model.jsonl
manifest.json
npm run verify:samplesWhen backend sample assets change, sync them into dl-agent and run the privacy guard before publishing.
npm run sync:samples
npm run verify:samplesdl-agent is split by runtime, agent instructions, workflow docs, request templates, sanitized samples, scripts, skills, and future MCP packaging so each surface has a clear owner and verification path.
dl-agent/
package.json
package-lock.json
.env.example
.editorconfig
.gitignore
.github/
workflows/ci.yml
ISSUE_TEMPLATE/
bug_report.md
feature_request.md
pull_request_template.md
agents/
AGENTS.md
CLAUDE.md
OPENCLAW.md
AGENT.md
assets/
logo.svg
docs/
architecture.md
commands.md
publishing.md
workflows.md
examples/body-files/
assembly.json
binding.json
check-model.json
alert-email-channel.json
alert-webhook-channel.json
meta.json
rule.json
run.json
packages/cli/
package.json
bin/driftledger.js
src/cli.js
src/core.js
test/core.test.js
README.md
samples/refund-payment-fund-consistency/
datasets/train.jsonl
datasets/test.jsonl
datasets/test-with-anomaly.jsonl
models/demo_model.jsonl
manifest.json
README.md
scripts/
install.sh
sync-demo-assets.mjs
verify-demo-assets.mjs
README.md
skills/
README.md
driftledger-cli/
SKILL.md
examples/
scripts/
driftledger-incident-review/
SKILL.md
templates/
mcp/
README.md
CHANGELOG.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
LICENSE
SECURITY.mdnpm workspace scripts, version metadata, and Node.js engine constraints.
CI workflow, issue templates, and pull request template.
Brand assets reused by the README and website.
Executable entrypoint for dl and driftledger.
Argument parsing, config precedence, command mapping, and HTTP transport.
CLI command-contract tests.
Hosted install script plus sample sync and privacy verification utilities.
Ready-to-copy instruction contracts for Codex, Claude Code, OpenClaw, and generic shell agents.
Small request payloads for metadata, rules, runs, and alert channels that agents can copy, edit, diff, and pass with --body-file.
Sanitized model, training set, clean test set, anomaly test set, and manifest.
CLI-first workflow skill for install, auth, workspace, data, model, rule, RuleForest, alerts, and run operations.
Incident review skill for business drift summaries, alert delivery checks, and remediation handoffs.
Reserved surface for future MCP server or manifest packaging.
Architecture and publishing notes for maintainers.
Start with these files and let the agent replace IDs from previous JSON responses. Keep payloads in files so retries are reviewable.
POST body for metadata upsert. Omit field types unless you need to constrain inference with values from dl metadata col-types.
{
"table": {
"spId": "<spId>",
"nodeName": "payment_order",
"nodeType": "TABLE",
"riskLevel": "HIGH",
"appName": "billing",
"comment": "Payment order export"
},
"fields": [
{"fieldName": "order_id", "primaryKey": true, "joinKey": true},
{"fieldName": "paid_amount", "riskLevel": "HIGH"},
{"fieldName": "paid_status"}
]
}POST body for source binding upsert.
{
"metaTableId": 1001,
"dataSourceId": "<dataSourceId>",
"sourceName": "orders.csv",
"fieldMappings": {
"Order ID": "order_id",
"Paid Amount": "paid_amount",
"Status": "paid_status"
},
"primaryKeyFields": ["order_id"]
}POST body for turning raw tables into assembled data.
{
"displayName": "payment settlement assembly",
"inputDatasetIds": ["<rawDatasetId>"],
"riskModelId": "<riskModelId>",
"outputDatasetName": "payment-settlement-assembled",
"assemblyOptions": {
"anchor": "payment_order",
"joinMode": "LEFT_PRESERVE"
}
}POST body for reconciliation model create.
{
"spId": "<spId>",
"title": "Paid orders reconcile to access",
"version": "v1",
"riskLevel": "P1",
"modelType": "TM",
"checkerType": "DEFAULT",
"description": "Paid orders must unlock the matching entitlement and settlement row."
}POST body for rule add. ruleType must be one of the values returned by dl rule types.
{
"spId": "<spId>",
"title": "paid order unlocks entitlement",
"modelId": "<modelCode-or-id>",
"modelVersion": "v1",
"ruleType": "LOGIC",
"ruleContent": "paid_status == PAID -> entitlement_status == ACTIVE",
"state": "ONLINE",
"generateType": "CUSTOM",
"ruleTables": ["payment_order", "entitlement"]
}POST body for run submit.
{
"displayName": "payment ledger smoke",
"datasetId": "<assembledDatasetId>",
"riskModelId": 101,
"ruleScope": "PUBLISHED",
"selectedRuleIds": [],
"executionOptions": {"mode": "smoke"}
}POST body for alert channel upsert.
{
"displayName": "Finance incident inbox",
"channelType": "EMAIL",
"enabled": true,
"minSeverity": "HIGH",
"recipients": ["finance-ops@example.com"]
}POST body for webhook-based delivery.
{
"displayName": "Incident webhook",
"channelType": "WEBHOOK",
"enabled": true,
"minSeverity": "MEDIUM",
"webhookUrl": "https://example.com/driftledger-alerts",
"webhookSecret": "replace-with-shared-secret"
}Most failures are config, token, payload, or backend availability problems. The CLI prints JSON errors so an agent can branch on ok:false.
Inspect config and env precedence. Flags win over env, env wins over stored config.
dl doctor
dl config get
echo "$DRIFTLEDGER_API_URL"dl uses Default when no workspace is specified. Inspect stored config and override only for a non-default workspace.
dl workspace list
dl config get
dl config set --workspace <spId>
export DRIFTLEDGER_WORKSPACE_ID="<spId>"Validate the file before retrying; keep generated payloads in files for review.
node -e "JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))" meta.json
dl metadata upsert --body-file meta.jsonUse api request as a temporary escape hatch, then add a high-level command to the CLI.
dl api request GET /api/v1/token/verify
dl api request POST /api/v1/new-endpoint --body @payload.jsonList channels, send a test alert, and then inspect delivery logs filtered by the execution task.
dl alerts list
dl alerts test --channel <channelId>
dl alerts deliveries --task <taskId>