> ## Documentation Index
> Fetch the complete documentation index at: https://docs.redbark.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sure

> Sync transactions to a self-hosted Sure instance

<Info>
  This tool uses the Redbark REST API, which is in **beta**. Behaviour may change as the API evolves.
</Info>

Sure sync runs as a standalone Docker container that pulls transactions from the Redbark API and imports them directly into your Sure instance. It is not a dashboard destination.

<Info>
  This is a **self-hosted Docker tool**. You run it on your own infrastructure alongside your Sure instance.
</Info>

## Prerequisites

* A running [Sure](https://github.com/we-promise/sure) instance
* Docker installed on your machine or server
* A Redbark account with connected bank accounts
* A Redbark API key
* A Sure API key with `read_write` scope

## Setup

<Steps>
  <Step title="Get a Redbark API key">
    <Info>
      **Plan required:** Developer or Professional. API access is not available on the Saver plan.
    </Info>

    Log into [Redbark](https://app.redbark.com), go to **Settings > API Keys**, and create a new key. Copy it. It is only shown once.
  </Step>

  <Step title="Get a Sure API key">
    Log into your Sure instance, go to **Settings > Security > API Keys**, and create a key with `read_write` scope.
  </Step>

  <Step title="Find your Redbark account IDs">
    Run the tool with `--list-redbark-accounts` to see your connected accounts and their IDs:

    ```bash theme={null}
    docker run --rm \
      -e REDBARK_API_KEY=YOUR_API_KEY \
      ghcr.io/redbark-co/sure-sync:latest \
      --list-redbark-accounts
    ```
  </Step>

  <Step title="Find your Sure account IDs">
    Run with `--list-sure-accounts` to see your Sure accounts:

    ```bash theme={null}
    docker run --rm \
      -e SURE_URL=http://localhost:3000 \
      -e SURE_API_KEY=your-sure-api-key \
      ghcr.io/redbark-co/sure-sync:latest \
      --list-sure-accounts
    ```
  </Step>

  <Step title="Create your account mapping">
    Map each Redbark account to a Sure account using the format `redbark_id:sure_id`, comma-separated:

    ```
    ACCOUNT_MAPPING=acc_abc123:d5e6f7g8-1234-5678-abcd-ef1234567890,acc_def456:a1b2c3d4-5678-9012-cdef-345678901234
    ```
  </Step>

  <Step title="Configure environment variables">
    Create a `.env` file with your configuration:

    ```bash theme={null}
    REDBARK_API_KEY=YOUR_API_KEY
    SURE_URL=http://localhost:3000
    SURE_API_KEY=your-sure-api-key
    ACCOUNT_MAPPING=acc_abc123:d5e6f7g8-1234-5678-abcd-ef1234567890,acc_def456:a1b2c3d4-5678-9012-cdef-345678901234
    TAG_NAME=Redbark
    ```
  </Step>

  <Step title="Dry run">
    Preview what would be imported without writing any changes:

    ```bash theme={null}
    docker run --rm --env-file .env \
      ghcr.io/redbark-co/sure-sync:latest --dry-run
    ```
  </Step>

  <Step title="Sync">
    Run the sync:

    ```bash theme={null}
    docker run --rm --env-file .env \
      ghcr.io/redbark-co/sure-sync:latest
    ```
  </Step>
</Steps>

## Configuration

### Environment variables

| Variable           | Required | Default                   | Description                                         |
| ------------------ | -------- | ------------------------- | --------------------------------------------------- |
| `REDBARK_API_KEY`  | Yes      |                           | Your Redbark API key (`YOUR_API_KEY`)               |
| `SURE_URL`         | Yes      |                           | URL of your Sure instance                           |
| `SURE_API_KEY`     | Yes      |                           | Sure API key (`read_write` scope)                   |
| `ACCOUNT_MAPPING`  | Yes      |                           | Account mapping (`redbark_id:sure_id,...`)          |
| `REDBARK_API_URL`  | No       | `https://api.redbark.com` | Redbark API base URL                                |
| `SYNC_DAYS`        | No       | `30`                      | Number of days of history to sync                   |
| `CATEGORY_MAPPING` | No       |                           | Category mapping (see below)                        |
| `TAG_NAME`         | No       |                           | Tag to apply to all synced transactions             |
| `LOG_LEVEL`        | No       | `info`                    | `debug`, `info`, `warn`, or `error`                 |
| `DRY_RUN`          | No       | `false`                   | Set to `true` to preview without creating           |
| `BATCH_SIZE`       | No       | `25`                      | Transactions per batch (max 100)                    |
| `CURRENCY`         | No       |                           | Override currency for all transactions (e.g. `AUD`) |

### Category mapping (optional)

Map Redbark transaction categories to Sure category UUIDs:

```
CATEGORY_MAPPING=groceries:uuid1,transport:uuid2,dining:uuid3
```

The left side of each mapping is a Redbark category (case-insensitive). The available categories are:

| Category                  | Description                             |
| ------------------------- | --------------------------------------- |
| `Bank Fees`               | Bank fees and charges                   |
| `Entertainment`           | Entertainment and recreation            |
| `Food & Drink`            | Groceries, dining, cafes                |
| `Government & Non-Profit` | Government services, taxes, donations   |
| `Home Improvement`        | Home maintenance and improvement        |
| `Income`                  | Salary, wages, and other income         |
| `Loan Payments`           | Loan and debt repayments                |
| `Medical`                 | Healthcare and medical expenses         |
| `Merchandise`             | General retail purchases                |
| `Personal Care`           | Personal care and grooming              |
| `Rent & Utilities`        | Rent, electricity, water, internet      |
| `Services`                | Professional and other services         |
| `Transfer In`             | Incoming transfers between accounts     |
| `Transfer Out`            | Outgoing transfers between accounts     |
| `Transportation`          | Public transport, fuel, tolls           |
| `Travel`                  | Flights, accommodation, travel expenses |

Not all transactions have a category. Categories are assigned by the bank via CDR enrichment and may vary by institution.

Run `--list-sure-categories` to find your Sure category UUIDs. Categories that don't match a mapping are included in the transaction notes for reference.

### CLI flags

| Flag                        | Description                                                |
| --------------------------- | ---------------------------------------------------------- |
| `--list-redbark-accounts`   | List Redbark accounts and their IDs                        |
| `--list-redbark-categories` | List Redbark transaction categories (for category mapping) |
| `--list-sure-accounts`      | List Sure accounts and their IDs                           |
| `--list-sure-categories`    | List Sure categories and their IDs                         |
| `--dry-run`                 | Preview what would be created without writing              |
| `--days <n>`                | Override number of days to sync                            |
| `--help`                    | Show help message                                          |

## Running with Docker

### Docker run

```bash theme={null}
docker run --rm \
  --env-file .env \
  ghcr.io/redbark-co/sure-sync:latest
```

No volume is needed. Sure sync is stateless with no local cache.

### Docker Compose

```yaml theme={null}
services:
  redbark-sure-sync:
    image: ghcr.io/redbark-co/sure-sync:latest
    restart: "no"
    environment:
      - REDBARK_API_KEY=YOUR_API_KEY
      - SURE_URL=http://sure:3000
      - SURE_API_KEY=your-sure-api-key
      - ACCOUNT_MAPPING=acc_abc123:sure-acc-uuid
      - TAG_NAME=Redbark

  sure:
    image: ghcr.io/we-promise/sure:latest
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://...
      - REDIS_URL=redis://redis:6379
    depends_on:
      - postgres
      - redis

  postgres:
    image: postgres:16
    environment:
      - POSTGRES_DB=sure
      - POSTGRES_USER=sure
      - POSTGRES_PASSWORD=sure
    volumes:
      - postgres-data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    volumes:
      - redis-data:/data

volumes:
  postgres-data:
  redis-data:
```

### Kubernetes CronJob

```yaml theme={null}
apiVersion: batch/v1
kind: CronJob
metadata:
  name: redbark-sure-sync
spec:
  schedule: "0 */6 * * *"
  jobTemplate:
    spec:
      template:
        spec:
          restartPolicy: OnFailure
          containers:
            - name: sync
              image: ghcr.io/redbark-co/sure-sync:latest
              envFrom:
                - secretRef:
                    name: redbark-sure-sync-secrets
```

## Scheduling

Use cron or your orchestrator's scheduling to run syncs automatically:

```bash theme={null}
# Sync every 6 hours
0 */6 * * * docker run --rm --env-file /home/user/.redbark-sure-sync.env ghcr.io/redbark-co/sure-sync:latest >> /var/log/redbark-sure-sync.log 2>&1
```

## How deduplication works

Each synced transaction is tagged with a machine-readable marker in the Sure transaction notes:

```
[redbark:txn_abc123] | Category: groceries | MCC: 5411
```

On subsequent runs, the tool checks for duplicates using two methods:

1. **Exact match**: searches existing Sure transactions for `[redbark:<id>]` in the notes field
2. **Fingerprint match**: compares date + amount + normalised name to catch manually imported transactions

You can run the sync as often as you want. Duplicates are never created.

## Exit codes

| Code | Meaning                                                 |
| ---- | ------------------------------------------------------- |
| 0    | Sync completed successfully                             |
| 1    | Sync completed with errors (some transactions failed)   |
| 2    | Configuration error (missing env vars, invalid mapping) |
| 3    | Connection error (cannot reach Redbark or Sure)         |

## Troubleshooting

**Connection refused to Sure**
Make sure your Sure instance is running and reachable from the Docker container. If both services are in the same Docker Compose stack, use the service name (e.g. `http://sure:3000`) rather than `localhost`.

**Invalid API key**
Double-check your `SURE_API_KEY` has `read_write` scope. Read-only keys cannot create transactions.

**Account not found**
Verify your account mapping using `--list-redbark-accounts` and `--list-sure-accounts`. Redbark account IDs look like `acc_abc123` and Sure account IDs are UUIDs.

**Category mapping issues**
Use `--list-sure-categories` to find the correct category UUIDs. Unmapped categories are included in the transaction notes rather than being lost.

## Security

<Info>
  Your Redbark API key is only sent over HTTPS. Your Sure API key is sent to your own infrastructure. Never bake secrets into Docker images. Use `--env-file`, Docker Secrets, or Kubernetes Secrets. The tool is stateless and stores no transaction data locally.
</Info>

## Source code

The sync tool is open source: [github.com/redbark-co/sure-sync](https://github.com/redbark-co/sure-sync)