trainUs/website/content/docs/user-guide/index.en.md

title	description	weight	date
Reference	How to use TrainUs: exercises, combos, sessions, collections, execution, and statistics.	3	2026-06-16

This page describes every TrainUs screen in detail: available actions, form fields, keyboard shortcuts. For a general introduction, see [Getting Started]({{< relref "demarrage-rapide.en.md" >}}); for the "why" behind the choices, see [Understanding TrainUs]({{< relref "comprendre.en.md" >}}).

First Launch

The very first time you open TrainUs, a one-time warning modal explains two important constraints of the app:

• One tab at a time — TrainUs can only be open in a single browser tab at once. Opening it in a second tab causes errors.
• No private/incognito browsing — TrainUs does not work in private or incognito windows; your data would not be saved.

Click Got it to dismiss the modal — it will not appear again.

Home

The Home page (#/home) is the default landing page. It provides an overview of your recent training activity.

Activity Overview

Two stat cards at the top:

• Sessions (last 7 days): Number of training sessions executed in the past 7 days.
• Sessions (last 30 days): Number of training sessions executed in the past 30 days.

Recent Sessions

The 4 most recently executed sessions are shown as cards. Each card displays:

• The session title and the date it was executed (formatted for your language).
• The total duration of the session (if it was completed without exiting early).
• A compact inline summary of every exercise performed — actual reps, weight, and duration per set. Combo items are shown with their round count and exercise breakdown.
• A play button (▶) to immediately start a new run of that session.

Click the card itself (anywhere except the play button) to navigate to the session detail view.

If no sessions have been executed yet, an empty-state message is shown.

Note

: Sessions appear here only after being executed in Execution Mode. Creating a session in the form does not add it to this list.

History

Below the recent sessions, the History section shows all your past executions grouped by calendar day (most recent first).

• Each day heading shows the date, and each card beneath it shows one session execution with its duration, inline exercise summary, and a play button.
• Two date pickers (From / To) let you narrow the range. The default is the last 30 days.
• The filter applies immediately — no reload needed.

HTML Export

When you have execution history, an HTML export button (</> HTML) appears in the action bar. Clicking it generates a single self-contained HTML file of your home page — stats, recent sessions, and the current history range — without any navigation links, play buttons, or interactive controls. You're prompted to name the file before it's saved. The file can be saved, printed, or shared. Any images (such as the app icon) are embedded directly in the file.

---

Navigation

TrainUs uses a responsive navigation layout:

• Desktop (screen wider than 700px): A fixed sidebar on the left with labeled links.
• Tablet / Mobile (screen 700px or less): A bottom navigation bar with icons and labels.
• Small mobile (screen 400px or less): A compact bottom bar with icons only.

The navigation gives access to 7 sections: Home, Exercises, Combos, Sessions, Collections, Statistics, and Settings.

---

Keyboard Shortcuts

TrainUs supports keyboard shortcuts for faster navigation. Most shortcuts are ignored when the cursor is inside a text field, textarea, or select — exceptions are noted below.

Navigation Menu

Key	Action
Tab / Shift+Tab	Move focus into and out of the navigation menu
↑ ↓ ← →	Move focus between menu items (when one is focused)
Enter	Navigate to the focused menu item

List Views

These shortcuts are available on the Exercises, Combos, Sessions, and Collections list pages.

Key	Action
Tab / Shift+Tab	Move focus between cards in the list
N	Open the "New" form to create a new item
↓	Move focus to the next card in the list
↑	Move focus to the previous card in the list
Enter	Open the currently focused card
Escape	Clear list focus (deselect the focused card)

Form Views

These shortcuts are available on all create and edit forms (Exercise, Combo, Session, Collection). They work even when a text field is focused.

Key	Action
Ctrl+Enter	Save the form (same as clicking Save)
Escape	Cancel and go back without saving

Hover over the Save button to see the shortcut hint in a tooltip.

Detail Views

These shortcuts are available on the Exercise, Combo, Session, and Collection detail pages.

Key	Action
E	Open the edit form
Escape	Go back to the list view

Dialogs

Key	Action
Escape	Close the dialog

---

Exercises

The Exercises section is accessible via the Exercises link in the navigation. It lets you create, view, edit, search, and delete individual fitness exercises.

Exercise List

Route	#/exercises
Content	A list of exercise cards, or an empty-state message if none exist
Actions	Search (magnifying glass icon) and New (plus icon) in the action bar

The list displays each exercise as a card showing:

• Title (always visible)
• Reps badge (if default reps > 0) — e.g., "12 reps"
• Weight badge (if default weight > 0) — e.g., "10 kg"
• Asymmetric icon (if the exercise is asymmetric)

Click any card to open the exercise detail view.

Creating an Exercise

Route	#/exercises/new
Access	Click the + button in the action bar

Field	Type	Required	Notes
Title	Text	Yes	Must be unique across all exercises
Description	Textarea	No	Basic Markdown supported
Asymmetric	Checkbox	No	When checked, shows alternation options
Alternate	Radio group	No	Only visible when Asymmetric is checked
Default Reps	Number	No	Must be ≥ 0
Default Weight	Number	No	Must be ≥ 0
Image URLs	URL list	No	Add one URL at a time; must be valid HTTP(S)
Video URLs	URL list	No	Add one URL at a time; YouTube URLs are auto-embedded

Images or videos? Prefer images if you want to work offline: once an image has been displayed at least once on your device, it stays available offline. Videos, on the other hand, are loaded from the internet every time and therefore don't work without a connection.

Click Save to create the exercise. Click Cancel to go back without saving.

Exercise Details

Route	#/exercises/:id
Access	Click an exercise card in the list
Actions	Back, Edit (pencil), Delete (trash) in action bar

Displays all exercise information in read-only mode including images and embedded YouTube videos. The description is rendered as formatted Markdown (bold, italic, lists, code, etc.).

Editing an Exercise

Route	#/exercises/:id/edit
Access	Click the pencil icon in the action bar

The edit form is identical to the create form but pre-populated with current data.

Deleting an Exercise

Click the trash icon in the action bar. A confirmation dialog appears. If the exercise has past execution entries, the dialog shows how many will be deleted with it. Confirming permanently deletes the exercise — along with any execution log entries that reference it — and returns you to the list. The rest of each affected session log (its other exercises) is unaffected.

Searching Exercises

Click the magnifying glass icon in the action bar. As you type, the list is filtered in real time (with a short delay). The search matches exercise titles (case-insensitive, partial match). A clear (×) button appears inside the field once it has text — click it to empty the field without leaving search mode. Click the magnifying glass icon again or clear the field to restore the full list.

---

Combos

The Combos section lets you group exercises together — useful for supersets, circuits, or timed formats (EMOM, AMRAP, TABATA).

Combo List

Route	#/combos
Content	A list of combo cards, or an empty-state message if none exist
Actions	Search (magnifying glass icon) and New (plus icon) in the action bar

Each card shows: Title, Type badge (NONE / EMOM / AMRAP / TABATA), Exercise count.

Creating a Combo

Route	#/combos/new
Access	Click the + button in the action bar

Field	Type	Required	Notes
Title	Text	Yes	Must be unique across all combos
Description	Textarea	No	Basic Markdown supported
Type	Dropdown	No	NONE (default), EMOM, AMRAP, or TABATA
Timer Config	Number	No	Duration (minutes) for EMOM/AMRAP; Rounds for TABATA
Exercises	Ordered list	No	Add exercises from your library; reorder with arrows

Adding exercises to a combo:

1. Select an exercise from the dropdown and click Add Exercise.
2. For each exercise, set Reps (≥ 1) and Weight in kg (≥ 0).
3. Use the up/down arrows to reorder; use the trash icon to remove.

Click Save to create the combo.

Combo Details

Route	#/combos/:id
Access	Click a combo card in the list
Actions	Back, Edit (pencil), Delete (trash) in action bar

Displays combo information including the ordered exercise list with reps and weight per exercise. Exercise names link to their detail view. The description is rendered as formatted Markdown.

Editing a Combo

Route	#/combos/:id/edit
Access	Click the pencil icon in the action bar

Deleting a Combo

Click the trash icon in the action bar. Confirming permanently deletes the combo.

---

Sessions

The Sessions section lets you build training sessions — ordered lists of exercises and/or combos. Sessions are what you execute during a workout.

Session List

Route	#/sessions
Content	A list of session cards, or an empty-state message if none exist
Actions	Search (magnifying glass icon), New (plus icon), and play button per card

Each card shows: Title, Item count, and a play button (▶) to start execution.

Creating a Session

Route	#/sessions/new
Access	Click the + button in the action bar

Field	Type	Required	Notes
Title	Text	Yes	Must be unique across all sessions
Description	Textarea	No	Basic Markdown supported
Items	Ordered list	No	Mix exercises and combos; reorder with arrows

Adding items to a session:

1. Choose the item type: Exercise or Combo.
2. Select an item from the corresponding dropdown and click Add.
3. For each item, set:
   • Repetitions (≥ 1) — for a combo, this is the number of full passes through the combo's exercise list.
   • Weight in kg (≥ 0) — overrides the exercise's default weight during execution.
4. Use the up/down arrows to reorder; use the trash icon to remove.

Click Save to create the session.

Session Details

Route	#/sessions/:id
Access	Click a session card in the list
Actions	Back, Play (▶), Edit (pencil), Delete (trash) in action bar

Displays the description (rendered as formatted Markdown) and the ordered list of items with their reps and weight. Item names link to their detail view.

Editing a Session

Route	#/sessions/:id/edit
Access	Click the pencil icon in the action bar

The edit form is identical to the create form but pre-populated with current data.

Deleting a Session

Click the trash icon in the action bar. A confirmation dialog appears; if the session has past execution logs, it shows how many will be deleted with it. Confirming permanently deletes the session along with all of its execution history — this cannot be undone.

---

Collections

The Collections section lets you group training sessions into ordered sets — useful for organizing weekly plans, training phases, or themed workouts.

Collection List

Route	#/collections
Content	A list of collection cards, or an empty-state message if none exist
Actions	Search (magnifying glass icon) and New (plus icon) in the action bar

Each card shows: Label and Session count badge (e.g., "3 sessions").

Creating a Collection

Route	#/collections/new
Access	Click the + button in the action bar

Field	Type	Required	Notes
Label	Text	Yes	Must be unique across all collections
Sessions	Ordered list	No	Add sessions from your library; reorder with arrows

Each session can appear at most once in a collection. Click Save to create the collection.

Collection Details

Route	#/collections/:id
Access	Click a collection card in the list
Actions	Back, Edit (pencil), Delete (trash) in action bar

Displays the ordered list of sessions. Session names link to their detail view.

Editing a Collection

Route	#/collections/:id/edit
Access	Click the pencil icon in the action bar

Deleting a Collection

Click the trash icon in the action bar. Confirming permanently deletes the collection (sessions are not deleted — only the grouping is removed).

---

Export / Import Data

TrainUs can export and import your data as JSON files. This lets you share data between devices, collaborate with other users, or keep structured backups of individual entity types.

Exporting Data

You can export from multiple places:

From	Scope
Exercise / Combo / Session / Collection list view	All items of that type, or only the matching ones if a search filter is active (download icon in action bar)
Exercise / Combo / Session / Collection detail view	Single item (download icon in action bar)
Settings → Export Data	Any combination of entity types (filter dialog)

Before the file is saved, a dialog lets you rename it — it's prefilled with a default name built from the entity type and date (e.g., trainus-exercises-2026-05-26 or trainus-full-2026-05-26 for a full export from Settings). The .json extension is fixed and shown next to the name field. Press Save to accept the name (or just press Enter to keep the default), or Cancel to abort without saving anything.

Exporting a combo, session, or collection (from a list, a detail view, or the filtered selection) always bundles the entities it depends on — exporting a session also includes its combos and exercises, exporting a collection also includes its sessions, combos, and exercises — so the file can be imported on its own without missing references, even if you only selected one entity type in the Settings filter dialog.

Importing Data

To import data from a JSON file previously exported from TrainUs:

1. Click the upload icon on a list view, or click Import Data in Settings.
2. Select the .json file.

If the file is from your own account (same user), you'll see any conflicts where items with the same ID already exist, or where a different item already has the same title. For each conflict you can:

• Replace: Overwrite the existing item with the imported version (keeping its original ID in a title conflict).
• Skip: Keep your current item. Anything else in the same file that referenced the imported item (e.g., a combo using that exercise) is automatically redirected to your existing item instead.
• Use Replace All or Skip All for batch actions.

If the file is from a different user, you'll be asked to choose a short suffix (e.g., "JD"). All imported titles will have the suffix appended: "Push-ups [JD]". If you import from the same external user again later, the existing suffix is reused automatically — and if the suffixed title conflicts with something you already imported earlier, the same Replace/Skip choice applies.

A preview step shows you a summary of what will be imported before any changes are made. After import, a report shows how many items were added, updated, or skipped.

Managing Import Suffixes

After importing from other users, an Import Suffixes section appears in Settings. You can:

• Edit a suffix: Changing it automatically updates all titles across all entity types (exercises, combos, sessions, collections) that use the old suffix.
• Delete a suffix entry (does not remove the imported items themselves).

---

Execution Mode

Execution Mode lets you run a session step-by-step, logging the reps and weight you actually performed.

Starting a Session

• From the Sessions list: click the play button (▶) on any session card.
• From the Session detail view: click the play button in the action bar.

During Execution

The execution screen shows:

1. Progress bar — how many steps you have completed out of the total.
2. Current step card — the exercise you are doing right now, with editable reps and weight fields.
3. Next step preview — the upcoming exercise (title, reps, and combo context if applicable).

For asymmetric exercises, a Side button appears. Tap it to toggle between LEFT and RIGHT.

Press ✓ Done to log the current step and advance to the next one.

Exercise Details During Execution

The exercise title in the current step card is tappable. Clicking it expands a detail panel showing the exercise's description, images, and video links — useful for checking form cues mid-workout.

• Click the title → the panel expands and the timer (if active) pauses automatically.
• Click the title again → the panel collapses and the timer resumes.

If you had already manually paused the timer before expanding, it stays paused when you collapse — only timers paused by the expand are auto-resumed.

The panel closes automatically when you advance to the next step.

Combos in Execution Mode

When a session item is a combo:

• Each exercise in the combo is shown as its own step, with the combo name and round number displayed.
• Rounds advance automatically — completing the last exercise in a round moves straight to the first exercise of the next round, with no pause screen.
• After the last exercise of the last round, a final-round screen appears:
  • Continue → — move on to the next session item (or finish the session if none remain).
  • + One More Round — append an extra round and keep going.

EMOM	AMRAP

TABATA — work phase	TABATA — rest phase

EMOM and AMRAP — "Duration (min)" field: When adding an EMOM or AMRAP combo to a session, the Repetitions field is relabelled Duration (min) to make its meaning explicit. For EMOM, this is the total number of minutes: the app divides by the number of exercises in the combo to compute how many rounds to run (each exercise occupies one 60-second slot). For AMRAP, the duration is the countdown timer length.

Audio Cues

TrainUs uses short audio beeps to help you keep rhythm without watching the screen. Two sounds are used:

• bip — a soft short tone (440 Hz): a gentle signal or countdown tick.
• BIP — a louder longer tone (880 Hz): marks a significant event (phase change, time up).

Timer type	When	Sound
EMOM	Every 30 seconds remaining	bip
EMOM	2 s and 1 s remaining	bip
EMOM	Timer expires (auto-advance)	BIP
AMRAP	Each elapsed full minute (except last minute)	bip
AMRAP	Exactly at the halfway point of the total duration	BIP
AMRAP	30 s remaining in the last minute	bip
AMRAP	2 s and 1 s remaining	bip, bip
AMRAP	Timer expires	BIP
TABATA	Start of each work or rest phase	BIP
TABATA	Halfway through each work or rest interval	bip
TABATA	2 s and 1 s before each phase ends	bip, bip

The bip, bip, BIP pattern you hear at the end of each interval is an evenly-spaced 3-beat countdown (one beat per second) leading into the next phase.

Prefill from Last Run

When you re-run a session, the reps and weight fields are prefilled with your values from the most recent run of that session. On the first run, fields default to the values configured on each session item.

Exiting Mid-Session

Press the ✕ button at any time to exit. Steps you already completed are saved to history; unfinished steps are omitted. The session appears in history as a partial run.

Headset / Media-Key Control

If your device and browser support it, you can control a running session with headphone buttons, OS media keys, or lock-screen controls — useful when your phone is locked away in a pocket or armband:

Control	Effect
Play / Pause	Pauses or resumes the active timer (EMOM, AMRAP, TABATA)
Next	Same as tapping ✓ Done (or Continue, on a round/time-up screen)
Previous	Goes back to the previous step — also available on-screen as a ◀ button next to Done
Stop	Exits immediately, no confirmation (steps already done stay saved)

Going back to a previous step and completing it again logs it a second time; nothing already saved is removed. The lock screen / headset display shows the exercise you are currently on.

This feature depends on your browser and OS supporting the Media Session API — where it isn't supported, the app works exactly as before, just without headset control.

Voice Announcements

During execution, a synthesized voice announces the exercise title whenever a new step begins — handy when you're not looking at the screen. For EMOM and TABATA combos, the app also pre-announces the next exercise ("Next: Squat") a few seconds ahead: 10 seconds before an EMOM slot ends, and as soon as a TABATA rest phase starts.

The voice follows your selected language and shares the same volume as the audio beeps. You can turn it off in Settings → Sound with the Voice announcements checkbox; it depends on your browser supporting speech synthesis — where it isn't supported, the app works exactly as before, just silently.

---

Statistics

The Statistics page is accessible via the Statistics link in the navigation.

Database Creation Date

At the top of the page: "You are using TrainUs since [date]" — when you first installed the app. The date format updates when you switch languages.

Date Range Filter

Four tabs let you focus charts and summary cards on a specific period:

Tab	Period
7 days	Last 7 days
30 days	Last 30 days (default)
3 months	Last 3 months
All time	All recorded history

Summary Cards

Card	What it shows
Sessions	Sessions executed in the selected period
Exercises done	Individual exercise sets completed in the period
Day streak	Consecutive calendar days (ending today) with at least one session; always calculated across all history

Frequency Chart

A bar chart showing how many sessions you executed per week or per month. Use the Per week / Per month toggle to switch the grouping.

Volume Chart

A bar chart showing the total volume (reps × weight in kg) per session execution over time. Only weighted exercises (weight > 0) contribute to volume.

Progression Chart

A line chart showing how your reps and max weight for a specific exercise evolve over time. Two lines are drawn on independent Y-axes — reps on the left, weight on the right.

1. Select an exercise from the dropdown.
2. Only exercises with at least one logged set appear in the list.

---

Settings

The Settings page (#/settings) lets you configure your preferences, manage your identity, and back up or restore your data. For the database and JSON export/import sections, see also [Understanding TrainUs]({{< relref "comprendre.en.md" >}}) and the [How-to Guides]({{< relref "guides-pratiques.en.md" >}}).

Language

Select your preferred language (English or Français). The entire interface updates immediately. Your choice is saved and applied on next launch.

User Name

Enter your name. The value is saved when you leave the field. Empty or whitespace-only names are rejected.

User ID

Your unique identifier, generated automatically on first launch. Read-only. Used internally to identify your data during import/export.

Theme

Switch between Light and Dark color schemes. Applied immediately and saved for future visits.

Sound Volume

A slider sets the volume of the bip/BIP sounds used during timed combos (EMOM, AMRAP, TABATA) — see Audio Cues. The setting is applied immediately and saved for future sessions. Click Test to preview both sounds (bip then BIP) at the current volume.

Download Database

Click Download Database to export a full backup of your data as a raw SQLite file. A dialog prompts you to confirm or rename the file before it's saved; the default name is:

trainus-{version}-backup-YYYYMMDD-HHhMMmSSs.sqlite3

The timestamp uses your local time and is zero-padded for easy sorting. This file can be restored using the Restore function, or inspected with any SQLite tool (e.g., DB Browser for SQLite). Cancelling the dialog leaves your backup status unchanged — the same prompt also appears for the mandatory backup on the update screen, and the Update button stays disabled until you actually save the file.

Restore Database

The Restore function replaces all your current data with the contents of a previously downloaded database file.

Steps:

1. Click Restore Database and select a .sqlite3 or .db file.
2. A confirmation dialog warns you that all current data will be replaced.
3. A spinner appears during the restore process.
4. A report card shows the result.

On success: a green header, a list of restored tables with row counts, and an optional note if the schema was adapted from an older version. Settings (name, language, theme) are updated in-place — no page reload needed.

On failure, the report shows a specific error:

Error	Meaning
Invalid file	Not a valid SQLite database or corrupted
Incomplete database	Missing required tables (not a TrainUs file)
Incompatible version	No migration path from this schema version
Adaptation failed	Schema migration from an older version failed
Restore failed	Error during the data copy process

Initialize Database

Permanently deletes all your data and resets the database to its initial state.

Steps:

1. Click Initialize Database.
2. Check the confirmation checkbox: "I understand that this will permanently delete all my data and cannot be reversed."
3. Click Initialize Database to proceed.
4. The page reloads with a fresh database.

Warning: This action cannot be undone. Use Download Database first if you want to keep your data.

Backup Reminder

TrainUs shows a warning button (⚠) in the action bar when your last backup is older than the configured interval (default: 7 days), or when you have never backed up.

• What it shows: Days since your last backup, or "No backup yet".
• Click the button: Takes you to the Settings page, scrolling to the Database section.
• The reminder persists until you back up or adjust the interval so the last backup is no longer stale.
• Grace period: Fresh databases (created within the last 7 days, or the configured interval) do not show the warning immediately.

App Updates

App updates preserve your data — you never need to export and re-import anything when a new version of TrainUs is released.

When a new version is available, TrainUs shows an Update available dialog. Choose Update now to apply it immediately — a short "Updating…" spinner is shown while the new version takes over and the app reloads — or Later to keep working; the dialog comes back the next time you open the app. The dialog never interrupts a workout: if you are executing a session, it waits until you leave the execution screen.

If an update changes the database structure, TrainUs shows a one-time update screen at startup. As a safety measure, it asks you to download a backup of your data first; the Update button becomes available once the backup has been saved. The update then runs in a few seconds and the app continues with all your data in place. If anything were to go wrong, your data is left unchanged and you hold the backup you just downloaded.

The regular backup reminder remains your day-to-day safety net.

In the Database section, you can also see:

• Last backup date — when you last downloaded or restored a backup.
• Remind me every N days — configurable interval (1–365, default 7).

Export / Import Data

Export Data opens a filter dialog where you select which entity types to include. You can export any combination of exercises, combos, sessions, collections, and execution logs.

Import Data opens a file picker for a .json file previously exported from TrainUs. See Import / Export Data above for details on the import flow and collision handling.

Import Suffixes

When you have imported data from other users, this section shows all registered suffixes. Each entry displays the external user's name and their assigned short tag. You can edit or delete entries — see Managing Import Suffixes above.

Credits

Click the Credits button to open the Credits dialog. It lists the open-source resources used to build TrainUs:

• Mighty Force (app icon) — by Delapouite, from game-icons.net, license CC BY 3.0. game-icons.net is maintained by Lorc, Delapouite & contributors.
• Bootstrap Icons (UI icons used throughout the application) — from icons.getbootstrap.com, license MIT.
• Third-party libraries — Vue, Vue Router, Vite, SQLite WASM, Chart.js, vue-chartjs, i18next, i18next-vue, Prettier, vite-plugin-pwa, marked, DOMPurify.
• Testing Tools — Playwright, pytest.

About TrainUs

Click the About TrainUs button to open the About dialog. It shows:

• App Version — the current version of TrainUs (e.g., 1.0.0).
• DB Version — the current database schema version.
• Created by — David Florance.
• License — GNU AGPL v3.
• Links — links to the project repository and website.
• Copyright Notice — a short copyright statement and AGPL license summary shown directly in the dialog.
• View License — opens the full GNU AGPL v3 license text in a dialog.

---

Appendix: Markdown Cheat Sheet

All description fields (exercises, combos, sessions) accept a subset of Markdown. What you type in the field is already close to what you see, but here's a quick reminder:

You type	You get
**bold**	bold
*italic*	italic
- item	item
1. item	item
`code`	code
[text](https://...)	text