§2. Features

2.1. Quick start

These three steps cover most cases:

1. /tracel inspect: turn on the inspector, then click a block to see its history
2. /tracel lookup u:Steve t:1h: see what Steve did in the last hour
3. /tracel rollback u:Steve t:1h s:50b #preview: check what would be restored. If it looks right, run the same command without #preview

2.1.1. Commands

Command	What it does	Permission
/tracel lookup <flags>	Searches events with filters	tracel.lookup
/tracel inspect	Turns the inspector on or off	tracel.inspect
/tracel near	Searches events around you	tracel.near
/tracel player <name>	Shows a player's activity report	tracel.player
/tracel rollback <flags>	Rolls the world back to its state at the start of the time window	tracel.rollback
/tracel rollback undo	Undoes the last rollback	tracel.rollback
/tracel preset ...	Manages presets	tracel.preset
/tracel data export	Saves the history to a file	tracel.data
/tracel data import <file>	Replaces all history with a snapshot	tracel.data
/tracel data migrate coreprotect	Imports CoreProtect history	tracel.data
/tracel data purge ...	Deletes history	tracel.data
/tracel status	Shows the status panel	tracel.status

2.2. Looking things up

Four commands read history. Nothing in them changes the world, so you cannot hurt anything by experimenting. They differ mostly in how much you have to type:

Command	Use it when	Permission
/tracel lookup <flags>	You know what you are looking for: a player, a block, a time window, or an action. Add flags to narrow it down	tracel.lookup
/tracel inspect	Block inspect: click and inspect	tracel.inspect
/tracel near	Something just happened right here	tracel.lookup
/tracel player <name>	You want to know about player's activity	tracel.player

Every command accepts the same flags. Press Tab after the command and Tracel lists what makes sense here — flags you have already used and flags that contradict one another are hidden.

2.2.1. Lookup

Below is an example of the lookup command. Pick the time and the scope, and add flags only when you need them. Most of the time you won't.

Results are folded by default, so a wall of identical lines doesn't bury the story. Twelve placements in a row become "Placed ×12", with the first and last time. Want every record on its own line? Add #each.

Hover a line to see the exact time, the coordinates and the player's gamemode. If the record was rolled back, the tooltip also tells you when it was undone and how long ago.

If you need to show the evidence to someone else, click "Export". The results are uploaded to a PrivateBin server and you get a link to share.

Note

Tracel cares about your privacy. PrivateBin encrypts the paste in your server before it is sent, so the paste host cannot read it, and the link expires on its own after three days.

If you're an admin, you can point Tracel at your own PrivateBin instance in config.toml.

2.2.2. Inspect

/tracel inspect toggles the inspector. While it is on, click any block or container and its history prints in chat. Click again elsewhere, run the command a second time to turn it off.

2.2.3. Near

The same as lookup, but /tracel near [flags] answers on question: what happened around me? A lookup centered on you, defaulting to a 16-block radius over the last 15 minutes. Anything you pass overrides the defaults.

Some command examples:

/tracel near
/tracel near t:2h
/tracel near s:64b a:chat

2.2.4. Player

/tracel player [nickname] shows you one-screen report on a player: how active they were, where, and what they did to the world. Works for offline players too — Tracel remembers people who have gone to bed.

2.3. Rollback

Lookup tells you what happened. Rollback makes it not have happened.

Warning

A Tracel rollback is not a CoreProtect rollback. It does not replay the log backwards: it restores the world to the state it had when your time window opened, and it follows items through crafts, chests and pockets to wherever they are now.

That makes it considerably smarter — it can take a stolen diamond back out of a crafted block and leave the thief's own diamonds alone — and it means the old habits (huge radius "just in case", running it twice "in case it missed something") are not needed and sometimes backfire.

The point of all this is that you don't have to suffer. A griefer blows up a warehouse, half the server picks up the loot, somebody crafts with it, somebody stuffs it into an ender chest, somebody dies and drops it. With a classic rollback you repair the scenery and then spend an evening hunting duplicates through inventories. With Tracel you run one command, and the items go back to the chests and barrels they came from, no matter who is holding them now.

tracel_rollback.mov

/tracel rollback needs two things: how far back (t:) and how far around (s:). Everything else narrows it down.

Warning

One thing to keep in mind: t: is not "undo what happened in the last 30 minutes" — it is "put things back the way they were 30 minutes ago".

For most changes those are the same thing. For a block that someone built and someone blew up inside the window, they are not (it stays gone; it did not exist 30 minutes ago).

Some command examples:

/tracel rollback t:30m s:20b
/tracel rollback u:Steve t:1h s:50b
/tracel rollback u:Steve t:1h s:50b #items
/tracel rollback a:explosion t:10m s:30b #explosion

To undo rollback, use /tracel rollback undo. It takes the last rollback you made back.

tracel_rollback_undo.mov

You can also preview first. Run the preview, look at what blinks, read the summary, then do rollback. If the summary says 209 removed and you were expecting a handful, that is the moment to stop and look again.

tracel_rollback_preview.mov

2.4. Presets

A preset is a name for a pile of flags. Cleaning up after a griefer means typing the same t:30m s:30b #preview over and over, usually in a hurry, usually with a typo. Save it once and it's one short word from then on.

Command	Does
/tracel preset list	Lists your presets and the server's
/tracel preset add <name> <flags...>	Saves a preset (a new name, or replaces yours)
/tracel preset show <name>	Shows its flags, owner and buttons
/tracel preset share <name>	Makes it a server preset — everyone with tracel.preset can use it
/tracel preset unshare <name>	Takes a server preset back as your own
/tracel preset delete <name>	Deletes it

Preset names start with @ when used and are plain words when managed.

Some command examples:

/tracel preset add mini t:30m s:1c #preview
/tracel rollback @mini
/tracel lookup @mini

@mini here means /tracel rollback t:30m s:1c #preview for rollback and /tracel lookup t:30m s:1c #preview for lookup.

2.5. Data

Everything about keeping the history healthy: how it is doing, how to back it up, how to bring in history from elsewhere, and — when the time comes — how to throw the old stuff away.

Command	Does	Permission
/tracel data export	Snapshot the history to a file	tracel.export
/tracel data import <file>	Replace all history with a snapshot	tracel.export
/tracel data migrate coreprotect	Bring in CoreProtect history, read-only	tracel.export
/tracel data purge ...	Delete history	tracel.purge

Note

Anything that can lose data works the same way: you run it, Tracel shows a preview of what it would do, and nothing happens until you repeat the command with #confirm.

2.5.1. Export

/tracel data export writes a snapshot of the whole history to a single file.

Files land in plugins/Tracel/database/exports/ as database-<date>-<time>.tracel. The result message shows the file, its size, the time range it covers and the row count.

Warning

Never copy anything out of plugins/Tracel/database/ by hand. To back up or move history, use /tracel data export, and use /tracel data import to restore it.

2.5.2. Import

/tracel data import replaces all current history with a snapshot made by /tracel data export.

Warning

Import deletes everything you have now. All current history is erased and replaced with the file. Nothing is merged.

• Make an export first if you want to keep what's in the database. An import can't be undone
• Stopping only works at the start. #stop works while the file is being checked. Once the old history is erased, the import keeps going, and if the server crashes it finishes at the next start
• Only use files made by Tracel. A file that is damaged or from another version is rejected before anything is erased

2.5.3. Migration

Moving over from CoreProtect? Bring the old history along — you don't have to start from a blank page.

1. Leave CoreProtect's folder — config and database — in plugins/CoreProtect/. Tracel only reads the files
2. Run the migrator with /tracel data migrate coreprotect

Warning

Imported records can't be rolled back. CoreProtect and Tracel store changes differently. Tracel keeps a ledger of each change, but CoreProtect rows don't have that trail. You can find imported records in lookups, but a rollback won't restore them. The rollback report tells you how many it skipped

Also, old history is added, not replaced. Everything you recorded with Tracel stays. The imported records go next to it. Nothing gets imported twice

Note

SQLite databases are the tested path. MySQL-backed CoreProtect installations are not supported yet.

2.5.4. Purge

Purge deletes world history. There are two ways to run it:

• Automatically. Turn on [purge] in config.toml. It is off by default. When it is on, Tracel checks and deletes records older than the matching time for each kind
• By hand. Run /tracel data purge with the options you want

Some command examples:

/tracel data purge category blocks older 30d
/tracel data purge player Steve
/tracel data purge all

Without #confirm, the command only shows a preview. Add #confirm to actually delete.

Keyword	What it does
category <list>	Deletes only these kinds: blocks, items, containers, events. Separate several with commas
older <span>	Deletes only records older than a span, such as 30d, 2w, or 12h
world <name>	Deletes only what happened in that world
player <name>	Deletes only what that player did
all	Deletes everything in the database. It cannot be combined with other filters

The preview shows the scope and the size. For filtered purges, it also shows, for each kind, how many records match out of how many exist.

Tip

If you want to clean up quickly and don't want to wait, use an age-only purge, such as older 30d with no player or world. Tracel stores history in one file per day, so it can delete old days as whole files. This is fast.

Filtered purges (player, world) are slower. Tracel has to rewrite every day they touch, so the more days involved, the longer it takes.

2.6. Status

/tracel status is the dashboard.

Line	Meaning
Format	The database format version
Records	Approximately how many blocks, items and events are stored
Period	The oldest record → now
Size	The database on disk
Disk	Free space where the database lives, and what share of the disk that is
Auto-purge	off, or on and when it last ran. A * means the kinds have different keep times; hover for the interval and each one
Queue	Records captured and waiting to be written
Load	Records written per second
Rollbacks	none, or how many are running and how big
State	Plugin's state

2.7. Appendix

2.7.1. Flags

Flags are space-separated. Short and long names are interchangeable. Material names are plain Minecraft IDs. Tracel knows an item and the block it turns into are the same thing: i:redstone also finds redstone_wire, b:carrot finds the carrot crop.

Flag	Aliases	Meaning	Example
u:	user:	Player name(s), comma-separated	u:Steve,Alex
t:	time: after: before:	When	t:2h30m
s:	scope:	Where	s:20b
w:	world:	World name	w:world_nether
a:	action:	Action or cause, comma-separated — see actions	a:break,explosion
b:	block:	A block material	b:tnt
i:	item:	An item material	i:diamond
#blocks		Structure only — block and entity changes
#items		Material only — item and inventory movement
#explosion		Include the crater and destroyed container contents
#each		Lookup only: no folding, one line per record
#world		Lookup only: also show what happened naturally (growth, decay...)
#all		Lookup only: everything, natural changes included
#wide		Scan horizontally, ignore vertical distance
@name		Use a preset	@grief

2.7.2. Actions

a: takes the friendly names below, comma-separated. Prefix + or - where it exists to mean "added" or "removed".

Group	Names
Blocks	block / place (+block) / break (-block) / grow / click / sign
Entities	entity / +entity / kill (-entity)
Items	container (item, inventory) / craft
Both	explosion / projectile
Events	chat / command / session (join / +session, quit / -session) / death / hit (damage) / shoot (launch)

2.7.3. Time

Time zone is the server's. after: and before: are the same flag, kept because everyone's fingers know them from somewhere.

You type	It means
t:15m / t:6h / t:7d / t:2w / t:30s	The last N... (units: s, m, h, d, w)
t:1h30m	Units combine: ninety minutes
t:today	Since midnight
t:yesterday	All of yesterday
t:2026-10-04	That whole day
t:2026-10-04..2026-10-06	A date range, both days included
t:2026-10-04T21:00..2026-10-04T22:30	A precise window
t:2h..30m	From two hours ago until thirty minutes ago

2.7.4. Scope

Radius is measured from where you stand. Rollbacks may cap the radius.

You type	It means
s:20b	20 blocks around you
s:3c	3 chunks around you
s:block	The block you stand on
s:chunk	The chunk you stand in
s:sift	The whole of a world (same as w:)