The .badger file format

A .badger file is how Badger hands a routine, a gym, or a set of machines to someone else. It is a single JSON text file, so you can open one in any text editor and read all of it.

What a file holds

• A routine file holds a program: its days, exercises, planned sets and rep targets, supersets and tempo, and, where the program has them, progression rules, percentage sets and weekly waves.
• A gym file holds a gym's equipment: machines, attachments, bars, accessories, dumbbell and kettlebell racks, and plates.
• A machines file holds just machines.

A file never holds your workout history: no logged workouts, sets or PRs, no training max, and nothing about you. To move your own history to a new phone, use a backup instead (see moving to a new phone). The full list is under what a file does not carry.

Opening a file on your phone

Tap the file wherever it arrived (a message, an email, a download), or open it from your file manager (Files on an iPhone). Badger shows a preview of what the file will add before anything is saved.

Importing only adds. Nothing you already have is changed, and exercises you already have are matched by name and type, so they keep their history.

Where to find ready-made files

Programs has every program built into Badger as a file you can download and open. To have an AI write one for you, the Use your own AI guide has a prompt for it. The rest of this page is the specification, for anyone writing a file by hand, with a tool, or with an AI.

Specification

From here to the end, this page defines what a file may contain and what import does with it. Fields marked required must be present. Any other field may be left out or written as null, and either reads as absent. Unknown fields are ignored.

Keys marked "Needs Badger 1.1.12 or later" are ignored by older versions; see versions and compatibility.

Terms used below

• Slot: one exercise on one day of a routine, with its planned sets. A slot is a DayExercise.
• Progression group: the slots of one routine that share a progression_group_key, on any of its days. They progress as one: a single reference weight, failure counter, stage and remembered weight between them. A rule in the group reads sessions from its own day and from the days of the other members that carry a rule. A slot with no key is a group of its own.
• Training max: the number a set's percentage is taken from. A progression rule moves it, and it never goes on the bar itself.
• Reference weight: the number a slot's percentage sets are a percentage of. Under a rule whose reference_kind is training_max, it is the training max. Each lifter has their own, and a file never carries it. Slots in one progression group share one. A slot with no reference weight of its own takes another slot's; see percent_reference.
• Waved day: a day whose sets change by week of a repeating cycle (5/3/1's four weeks) or by stage. Each version of the day's sets is a variant. See Waves.
• Stage: on a stage-based day (GZCLP, StrongLifts), which of the day's set variants the slot is on, counting from 0. Only next_stage and reset_stage move it.
• Driver set: the one planned set whose logged reps some triggers read, marked with is_progression_driver.
• Missed session (a failure): a session of this slot in which at least one logged working set was left incomplete or came in under its planned minimum. A skipped set counts neither way. A session where every logged working set met its minimum is a success. A session with no completed set of the exercise at all is neither, and the rule ignores it.
• Failure counter: the run of missed sessions in a row. A success resets it to 0, and so does a consecutive_failures_at_least or stage_is_last clause firing. hold lets it move; none undoes this session's change to it.
• Remembered weight: the slot's weight as it stood while the slot was on its first stage, recorded each time the rule reads a session there. set_from_remembered restarts from it.

The envelope

Every file has the same five top-level fields. Import needs three of them.

Files Badger writes leave optional fields out rather than writing null.

A routine payload

type: "routine". The payload has four keys. Only routine is required: a missing days, exercises or machines reads as an empty list, though a routine needs days and exercise definitions to be of any use.

Two arrays are called exercises. The top-level one is an array of Exercise and defines what each exercise is. Each day's exercises is an array of DayExercise: that day's slots, which point at the definitions by name. A slot whose name matches no definition is skipped, and the import preview warns about it.

Routine

The object in the payload's routine key.

Day

The objects in days, one per session in the program.

Exercise

The objects in the payload's top-level exercises: the definitions the slots point at. List only the exercises the routine uses. Import matches each one against the recipient's library first, so most usually resolve to exercises they already have.

DayExercise

The objects in a Day's exercises array. Each is one slot: one exercise on that day, with its planned sets.

PredefinedSet

The objects in a DayExercise's predefined_sets, one per planned set. Fill in the fields the exercise type uses: weight and reps for a bench press, duration_seconds for a plank, distance for a row. Leave out fields that do not apply.

Waves: cycle_length and week_index

A day whose sets change from week to week is written once, not once per week. 5/3/1's four-week cycle is the standard case. Two keys do it, and they only make sense together. Both need Badger 1.1.12 or later.

• Day's cycle_length says how many weeks the cycle runs for. Absent means the day is not waved.
• Each PredefinedSet's week_index says which week that set belongs to, counting from 0. Absent means every week, which is how accessory work done all cycle long is written once.

A week_index that matches no week (negative, or at or above the day's cycle_length) is read as every week. The recipient starts the program at its first week: which week the sender is on does not travel.

The week counter belongs to the routine, not the day. It is one number that every waved day in the routine reads. It moves on once every day waved to the same length has been trained since the last move. Stage-based days (below) do not move it.

Each day reads the counter against its own cycle_length, so give every waved day in a routine the same length. cycle_complete fires when the counter wraps back to the first week. If lengths differ, each length moves the shared counter on its own schedule, and cycle_complete wraps at each day's own length.

Stage-based programs (GZCLP, StrongLifts) use the same two keys, with each week_index a stage and cycle_length the number of stages.

A slot whose rule has a next_stage or reset_stage clause, or any clause targeting stage, shows the variant for its current stage. The stage changes only when one of those clauses fires; in GZCLP and StrongLifts that happens when you stall. Every other slot shows the variant for the routine's current week.

A complete routine file

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, indented for reading. Files the app writes are minified, and whitespace makes no difference either way.

{
  "badger": "share/v1",
  "app_version": "1.1.11",
  "created_at": "2026-09-13T05:09:30.410810Z",
  "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": []
  }
}

For files that use progression rules, percentage sets and waves, open the files on the Programs page, such as 531-bbb.badger and gzclp.badger.

Progression rules

A slot's progression rule says what happens to its weight after each session. It is a Progression object holding a list of Clause objects. The example below shows a complete one.

Progression

The object in a DayExercise's progression key. At most one per slot. Needs Badger 1.1.12 or later.

The rule travels; the sender's progress against it does not, including their training max (see what a file does not carry). A training_max key written into a file is an unknown key and is ignored.

Clause

The objects in clauses. Each one is a trigger and the action it fires. count, reps_min and reps_max belong to the trigger; target, amount, amount_unit and percent belong to the action. The terms missed session, failure counter, stage and remembered weight are defined under Terms used below, at the start of the specification.

Example: a linear rule

Add 2.5 kg after every session in which all working sets hit their target, take 10% off after three missed sessions in a row, and otherwise keep the weight. This is one slot, with three sets of 5:

{
  "exercise_name": "Barbell Back Squat",
  "exercise_type": "weight_reps",
  "progression": {
    "scheme": "linear",
    "cadence": "session",
    "reference_kind": "working_weight",
    "clauses": [
      {
        "trigger": "consecutive_failures_at_least",
        "count": 3,
        "action": "add_percent",
        "target": "working_weight",
        "percent": -10
      },
      {
        "trigger": "all_sets_met",
        "action": "add_absolute",
        "target": "working_weight",
        "amount": 2.5,
        "amount_unit": "kg"
      },
      {
        "trigger": "always",
        "action": "hold",
        "target": "working_weight"
      }
    ]
  },
  "predefined_sets": [
    {
      "is_warmup": false,
      "reps": 5
    },
    {
      "is_warmup": false,
      "reps": 5
    },
    {
      "is_warmup": false,
      "reps": 5
    }
  ]
}

Badger reads the clauses in order and fires the first that matches. After a third missed session in a row, the first clause takes 10% off and resets the failure counter to 0. After a session where every planned working set reached 5 reps, the second clause adds 2.5 kg. Any other session reaches the always clause, and the weight holds while the failure counter still moves.

The rule ends with always, every clause names a target, and add_absolute and add_percent carry the amount and percent they need, so none of the conditions above drops it.

Gym and machines payloads

type: "gym" shares a whole gym: the gym itself, its machines, attachments, bars and accessories, which of each belong to it, its dumbbell and kettlebell racks, and its plates. type: "machines" is the smaller version: one key, machines, an array of Machine, with no gym, bars, accessories, or inventory.

A gym file carries what describes the gym. Notes about a machine travel. Your photo of it, and the setup cues you saved against one exercise on it, stay on your phone.

Equipment is defined in its own arrays, and the four gym_* lists name which of it belongs to this gym, so one machine can belong to several gyms. Files Badger writes list exactly the objects defined beside them.

Leave a membership list out to include everything defined in the file. Writing it as [] means none of them, which leaves the gym with nothing of that kind and is almost never what you want.

Machine

The objects in machines, in a routine payload and a gym or machines payload alike. In a routine payload, importing the machines is a toggle the recipient controls. In a gym or machines payload, machines are always created.

Bar

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

Accessory

The objects in accessories: a band, a chain, a set of suspension straps, or another add-on.

Rack

The objects in racks: the dumbbells or kettlebells a gym owns. List every weight on the rack, since racks do not step evenly (5, 10, 15 up to 50, then a jump). The plus and minus buttons step through this list when you log.

One entry per equipment-and-unit pair, so a gym with kilogram kettlebells and pound dumbbells carries two. Nothing is converted between them: 45 in a pound rack is a 45 lb dumbbell.

PlateInventory

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

One entry per unit, and nothing converts between them. A gym still on Badger's built-in default plates writes no plate_inventory at all.

What import does

• Nothing is 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. The same name with a different type is a different exercise. With no match, the exercise is created in the named category, which is created too 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.
• It is one transaction. A file that fails partway through leaves your database exactly as it was.
• Days, slots, and sets import in array order.
• A warmup never carries a rep range or an open target. Import drops reps_max and is_amrap from a warmup set. A working set carrying both keeps the open target and loses the range.
• An unreadable progression rule is skipped whole and counted in the import preview's warning; the rest of the file imports normally. What drops a rule is listed with the clause fields. Per-set flags are repaired instead: extra driver sets are cleared as described under is_progression_driver, a driver on a warmup is cleared, and a week_index or percent_of_reference that cannot mean anything is read as absent. An intensity target is repaired as described under target_rpe.
• Files over 10 MB are refused without being read.

What a file does not carry

A routine file is the plan, and only the parts of it that work for a different lifter in a different gym.

• No history. No workouts, no logged sets, no PRs. 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. In a gym file, notes on a machine, attachment, bar or accessory do travel. The setup cues you save against one exercise on one machine never do.
• No default attachment, default bar, or default grip on a slot, and no superset group color; the recipient's palette assigns it. (An accessory's color does travel.)
• No training max, and no progress against a rule. A slot's progression rule travels. The training max it multiplies does not, and neither does any counter behind it: a run of missed sessions, a stage, a cycle position, which session was last evaluated. The recipient sets their own training max, from their own history, the first time they run the program.
• 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. That includes an exercise's own Log left and right separately setting, which never travels, like its per-side weight setting. A machine's unilateral_mode does.
• No photos of machines, attachments, or bars.
• Nothing about you. No account, no device identifier, no settings, no training notes.

Versions and compatibility

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. 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. See also the promise.

• Optional keys are left out when unused. A file that uses none of the newer keys is byte-identical to one written before they existed, and an older copy of Badger reads it unchanged.
• 1.1.12 keys. progression, progression_group_key, percent_reference, percent_of_reference, is_progression_driver, cycle_length, week_index, target_rpe and target_rir need Badger 1.1.12 or later. An older version ignores progression and imports the slot without a rule. When a percentage set also carries a weight, an older version that has never heard of percent_of_reference still finds the weight as the target. It reads a set with an intensity target as the same set with no target.
• is_amrap is omitted when false. Because reps still holds the minimum, an older version reads an open target as an exact one.
• logs_weight_per_side: older versions ignore the key and lose nothing else.
• 1.1.14 keys. A machine's unilateral_mode and a set's is_unilateral are omitted when not set. An older version ignores both and imports the routine or machine without them, so the sets read as ordinary both-arms sets.
• Older values still read. machine_type: "plateLoaded"; the camelCase plate_calculator_mode values; a machine's bar_weight_kg (always kg) in place of bar_weight and bar_weight_unit; and the retired sort_order field, which is ignored.