The .badger file format

A .badger file is how Badger hands a routine, a gym, or a set of machines to somebody else. It is a single UTF-8 JSON file. Nothing is compressed, encoded, or encrypted: open it in any text editor and you can read the whole thing.

This page documents it properly because three groups of people want it. Curious users, who would rather see what they are importing before they import it. Tool authors, who want to write something that emits a file Badger can read. And AI assistants: point yours at this page, hand it the example, and ask it to write you a program as a valid .badger file. The BYO-AI guide has prompts for exactly that, and the program gallery has seven real files to read.

The envelope

Every file, whatever it holds, has the same five top-level fields.

Optional fields are omitted rather than written as null, and unknown fields are ignored on the way in. Writing a file by hand is therefore forgiving: include what you mean, leave out what you do not.

A routine payload

type: "routine". The payload has four keys:

Note that two arrays share the name exercises and they hold different types: exercises at the top level is an array of Exercise, defining what each exercise is, while a day's exercises is an array of DayExercise, saying what that day does and referencing the definitions by name. Every name a day uses should have a definition in the top-level list - a slot whose name matches no definition is skipped - the import preview counts these and warns you before anything is written.

Routine

The object in the payload's routine key.

Day

The objects in days.

An array. One entry per session in the program.

DayExercise

The objects in a Day's exercises array: one slot in the plan.

PredefinedSet

The objects in a DayExercise's predefined_sets.

A planned set. Fill in the fields the exercise type actually uses: weight and reps for a bench press, duration_seconds for a plank, distance for a row. Fields that do not apply are simply left out.

Exercise

The objects in the payload's top-level exercises: the definitions the day slots reference.

The definitions the days point at. Keep it to the exercises the routine actually uses; a recipient's existing library is matched first, so most of this list usually resolves to exercises they already have.

Machine

The objects in machines, here and in a gym payload alike.

Equipment settings. In a routine payload this list is reference data: importing the machines is a toggle the recipient controls. In a gym or machines payload the same object is the point of the file, and machines are always created.

Gym and machines payloads

type: "gym" shares a whole gym: the gym itself, its machines, its attachments, its bars and accessories, which of each belongs to it, and the equipment that is a list rather than an object - the dumbbell and kettlebell racks, and the plates.

The line it draws is worth stating plainly, because it decides every field below. What describes the gym travels; what describes you does not. Notes about a machine describe the machine, so they go. Your photo of it, and the setup cues you saved against one exercise on it, describe you, so they stay.

Definitions and membership are separate on purpose, mirroring the app: machines and attachments are global there, and a gym holds links to them, so one machine can belong to several gyms. In a file Badger writes, the membership lists always name exactly the objects defined beside them - the split is structure, not extra information to fill in.

All four membership lists follow the same rule, which matters if you are writing a file by hand: leaving one out means "all of them", and writing it as [] means "none of them". Those are different, and the second one is almost never what you meant - a gym whose machines belong to no gym is a gym with nothing in it. Say nothing and everything you defined lands at the gym, which is the obvious reading of a gym file and therefore the one the reader takes.

Bar

The objects in bars: a named bar, with its own weight.

A routine payload deliberately carries no default bar on a slot, the same as default attachment and default grip: which bar somebody reaches for is their setup, not your program.

Accessory

The objects in accessories: a band, a chain, a set of suspension straps, or an add-on that is none of those.

Rack

The objects in racks: the dumbbells or kettlebells a gym physically owns. Badger keeps these as a list rather than a step size because a real rack is not a grid - it runs 5-10-15 up to 50 and then jumps, and a kettlebell ladder is not a multiple of anything useful. The list is what the plus and minus buttons walk when you are logging.

One entry per equipment-and-unit pair, so a gym with kilogram kettlebells and pound dumbbells carries two. They are separate lists and nothing is converted between them: 45 in a pound rack is a 45 lb dumbbell, not a 99 lb one.

PlateInventory

The objects in plate_inventory: what the plate calculator has to work with.

One entry per unit, and again nothing converts. A file only carries a plate list somebody actually set up - a gym running on Badger's built-in defaults writes no plate_inventory at all, because those defaults are already in the app opening the file.

type: "machines" is the smaller version: one key, machines, an array of Machine and no gym, bars, accessories, or inventory.

A worked example

One routine, one day scheduled Monday and Thursday, two exercises. The bench press has a warmup set and three working sets of 8-10; the plank is timed. This is the real example-routine.badger, printed with indentation added: files the app writes are minified, and whitespace makes no difference either way.

{
  "badger": "share/v1",
  "app_version": "1.1.1",
  "created_at": "2026-07-25T23:42:17.697472Z",
  "type": "routine",
  "payload": {
    "routine": {
      "name": "Example Routine",
      "notes": "A two-exercise day, kept small enough to read.",
      "weight_source": "last_performance",
      "history_scope": "any_workout"
    },
    "days": [
      {
        "name": "Day 1",
        "scheduled_days": [
          1,
          4
        ],
        "exercises": [
          {
            "exercise_name": "Flat Barbell Bench Press",
            "rest_override_seconds": 180,
            "exercise_type": "weight_reps",
            "predefined_sets": [
              {
                "is_warmup": true,
                "reps": 8
              },
              {
                "is_warmup": false,
                "reps": 8,
                "reps_max": 10
              },
              {
                "is_warmup": false,
                "reps": 8,
                "reps_max": 10
              },
              {
                "is_warmup": false,
                "reps": 8,
                "reps_max": 10
              }
            ]
          },
          {
            "exercise_name": "Plank",
            "exercise_type": "time_only",
            "predefined_sets": [
              {
                "is_warmup": false,
                "duration_seconds": 60
              },
              {
                "is_warmup": false,
                "duration_seconds": 60
              }
            ]
          }
        ]
      }
    ],
    "exercises": [
      {
        "name": "Flat Barbell Bench Press",
        "type": "weight_reps",
        "category_name": "Chest"
      },
      {
        "name": "Plank",
        "type": "time_only",
        "category_name": "Core"
      }
    ],
    "machines": []
  }
}

What import does

Reading the file is the easy half. These are the rules that decide what it turns into.

• Nothing is ever overwritten. Import only adds. An existing exercise, machine, gym, or routine is never edited by a file you open.
• Exercises match on name and type, ignoring case and surrounding spaces. Same name, different type, means a different exercise, so a routine can never wire itself to the wrong one. No match, and the exercise is created, in the named category, which is itself created if it is new.
• Machines, attachments, bars, accessories, gyms, and categories match on name alone, again ignoring case and spaces.
• A routine name collision does not merge. Importing a routine whose name you already use gives you "Name (imported)", then "Name (imported) 2", and so on. You keep both and decide.
• It is one transaction. A file that fails partway through leaves your database exactly as it was.
• Order is array order. Days, slots, and sets import in the order they appear in their arrays - JSON arrays are ordered, and that order is the order. (Older files carrying the retired sort_order field still read; the field is ignored.)
• A warmup never carries a rep range or an open target. If a file puts reps_max or is_amrap on a warmup set, import drops it rather than storing a plan the app cannot show you. A working set carrying both has its range dropped: open wins.
• Files over 10 MB are refused without being read. A real export is a few kilobytes, so this only ever catches something that has gone wrong.

What a file does not carry

Worth knowing before you assume a share is a clone. A routine file is the plan, and only the parts of the plan that travel usefully between two different lifters in two different gyms.

• No history. No workouts, no logged sets, no PRs. Those are yours and they stay on your phone. To move your own history to a new phone, use a backup instead: see moving to a new phone.
• No notes below the routine level. Routine notes travel; per-day and per-exercise notes do not. A gym file is the exception that proves the rule: notes on a machine, attachment, bar or accessory travel, because they describe the equipment. The setup cues you save against one exercise on one machine never do - those describe you.
• No default attachment, default bar, or default grip on a slot - those stay personal setup. Superset group color also stays behind; the recipient's palette assigns it. (An accessory's color does travel, because that one is the thing's name rather than decoration.)
• No per-exercise detail beyond name, type, and category. An exercise that gets created on import starts blank: no instructions, no muscles, no rest default, no increment. Anything you already had keeps everything it already has.
• No photos of machines, attachments, or bars. A .badger file is a small text document, and your photo of a leg press is yours.
• Nothing about you. No account, no device identifier, no settings, no training notes.

The versioning promise

The version string exists so that files stay readable. Two commitments go with it. Unknown fields are ignored, so a file written by a newer Badger still opens in an older one, minus whatever that older version has no concept of. And if the shape ever has to change in a way that breaks, badger gets a new value and share/v1 keeps being read: a file you exported today should still import years from now.

That is the same commitment as the rest of the promise. Data you can get out is only worth something if it still opens later.