Question 1

What is a trecs recording?

Accepted Answer

A recording of the terminal session itself, not a video of it. trecs captures everything the terminal displays, with its timing: the text, the colours, the cursor movement, full-screen programs such as vim and htop. The result is a plain-text file of a few kilobytes that the player draws afresh at whatever size the viewer has.

Every command in it is a jump point, so a viewer goes straight to the step they need.

Question 2

How is that better than a screen video?

Accepted Answer

A video is a grid of pixels: soft on a phone, blurry at full screen, and unreadable once someone zooms in. A recording is text, so it is sharp at any size, it is a few kilobytes where the same session as video runs to hundreds of megabytes, and the output can be selected and copied instead of retyped.

It also shows the real thing: the actual output, the actual error and the actual fix, right beside your written steps. The interactive tour lets you try the player.

Question 3

How do I make a recording?

Accepted Answer

Install the recorder (download; Linux, .BSD and macOS), run trecs record, work as you normally would, and type exit or press Ctrl+D to finish. Then trecs-edit view to tidy it up and trecs upload to get a link. The full steps are in the documentation.

Question 4

Which shells does it work with?

Accepted Answer

Any. bash (4.4 or later), zsh and fish are started with prompt marks, which tell the recording exactly where each command and its output begin and end, whatever your prompt looks like. Other shells are recorded too, but without the marks the command boundaries are inferred from the prompt, which is less reliable.

Question 5

Can I record without typing, for example in CI?

Accepted Answer

Yes. trecs record -commands-file steps.txt types the commands in the file itself, one per line, so it needs no keyboard and no terminal. That also keeps a tutorial reproducible: change the script and record it again. -human-like adds the pauses a person makes.

Question 6

Can I narrate a recording?

Accepted Answer

Yes: trecs record -audio records your voice with the terminal (it needs ffmpeg). The audio stays in sync as viewers jump between commands.

Question 7

Can I fix a recording after the fact?

Accepted Answer

trecs-edit plays a recording back and lets you correct a command or its output, delete commands, add annotations, join several recordings into one with merge, and export the commands and output as Markdown. The original is kept as a backup before it is rewritten.

Question 8

What are annotations?

Accepted Answer

Notes you attach to a command or to a moment of the recording. They can pause playback where you want attention, appear as a card over the terminal, or be listed under their command in the player’s command list. There are also cue cards, shown before or after a command, such as a title card at the start.

Question 9

Who can see my recordings?

Accepted Answer

You choose, for each one: private (only you), unlisted (anyone with the link) or public (anyone can find and watch it). An unlisted link is not a secret: anyone who has it can pass it on, so do not use it for anything confidential.

Question 10

What if I record a password or a key by accident?

Accepted Answer

A terminal recording captures everything shown and typed, so check a recording before you upload it and use the editor to cut or mask anything that should not be seen. If a secret did appear in a recording that was visible to others, treat it as compromised and revoke it; deleting the recording does not undo the exposure. The Terms say more.

Question 11

How do I embed a recording in my docs?

Accepted Answer

The share menu on a recording’s page (or a right-click on the player) gives you the link, the link at the current time, an embed code, and an image link for a README.

Question 12

What do you get when I sign in with GitHub?

Accepted Answer

Your GitHub ID, user name and verified primary email address. We do not get your GitHub password or any access to your repositories.

Question 13

How do I delete my account and recordings?

Accepted Answer

From your settings, or by asking us. Your recordings and profile data are deleted from the live service within 30 days, and from backups within a further 90. The Terms have the details.

Question 14

Is trecs open source?

Accepted Answer

Yes. The recorder and the editor are free software, released under the GNU Affero General Public License, version 3 (AGPLv3), and developed in the open at github.com/solworktech/trecs.

Question 15

Our commitment to FOSS

Accepted Answer

The open-source project is the product, not a trial version of a paid one. The recorder and the editor are complete tools: you are not asked to pay to record, edit or share, and we do not hold back features to sell them back to you.

What the commercial licence adds is what the AGPLv3 is not meant to give away: a private, white-labelled platform, integrations with your own systems, and the right to rebrand and ship the recorder under your own terms. See Enterprise.

Question 16

Why the AGPLv3?

Accepted Answer

It keeps improvements free for everyone. Anyone may use, change and share trecs, but whoever distributes it, or runs a modified version as a service for others, must pass the source on under the same licence. Nobody can take it closed.

Question 17

What may I do with it, and what must I do?

Accepted Answer

You may use it for any purpose, including commercial work and at your employer, study and modify it, run it inside your organisation, and share copies. The key rule is this: if you distribute trecs, you distribute its source. Whenever you give anyone a copy, whether a binary, a package, a container image, or a copy bundled in your product, they must get the complete source under the AGPLv3, including your changes. Running a modified version as a service for other people carries the same duty.

You do not have to publish changes that you only use privately, inside your own organisation. The full explanation is in the README.

Question 18

Do my recordings fall under the AGPLv3?

Accepted Answer

No. What you record is yours, and the licence does not reach it.

Question 19

Can I bundle trecs in my product or rebrand it?

Accepted Answer

Under the AGPLv3 only if your product is released under it too, with its source. If you need to ship trecs, rebranded, inside a product that is not open source, that is what an enterprise licence is for.

Question 20

Can I contribute?

Accepted Answer

Please do: bug reports, fixes, documentation and ideas are all welcome. Read CONTRIBUTING.md first. Contributors sign a short agreement once (you keep your copyright), which lets us offer trecs under commercial licences as well as the AGPLv3.

Question 21

Do I need an enterprise licence to use trecs at work?

Accepted Answer

No. Using trecs in your company, including for commercial work, is fine under the AGPLv3, and so is modifying it for your own use. You need an enterprise licence only for what the AGPLv3 does not allow, such as distributing it without its source.

Question 22

What does an enterprise licence include?

Accepted Answer

A private, white-labelled instance of the trecs platform, on your servers or fully managed by us; integration with your ticketing, support or bug-tracking system; and white-labelling and distribution of the recorder. It also replaces the AGPLv3’s conditions with commercial terms, so you do not have to publish your modifications or ship your source. Read more.

Question 23

How do I get one?

Accepted Answer

Contact us and tell us what you have in mind. We will get back to you by email.