tee for splitting output in Linux CLI - Deep Dive

Overview - tee for splitting output

What is it?

The tee command in Linux takes the output of a command and splits it so you can see it on the screen and save it to a file at the same time. It reads from standard input and writes to standard output and files simultaneously. This helps you keep a record of what a command outputs without losing the live display. It is often used in scripts or command lines to log output while still showing it.

Why it matters

Without tee, you would have to choose between seeing command output on your screen or saving it to a file. This makes it hard to monitor processes live and keep logs simultaneously. Tee solves this by duplicating the output stream, making it easier to debug, audit, or save important information while working interactively. It improves productivity and reliability in command-line work.

Where it fits

Before learning tee, you should understand basic Linux commands, standard input/output, and redirection using > and >>. After tee, you can explore advanced shell scripting, process management, and logging techniques that use tee to capture outputs from multiple commands or background jobs.

Mental Model

Core Idea

Tee acts like a pipe that splits a river of output into two streams: one to the screen and one to a file.

Think of it like...

Imagine pouring water from a jug into a glass while also filling a bottle at the same time using a Y-shaped pipe. You get water in both containers without stopping the flow.

Command Output Stream
      │
      ▼
  ┌─────────┐
  │   tee   │
  ├─────────┤
  │         │
  ▼         ▼
Screen    File(s)

Build-Up - 7 Steps

1

Foundation

Understanding standard output basics

Concept: Learn what standard output is and how commands send their results to the screen.

In Linux, when you run a command like ls, it sends its results to the screen. This is called standard output (stdout). You can redirect this output to a file using >, for example: ls > files.txt saves the list to a file instead of showing it.

Result

The command output is saved in files.txt and not shown on the screen.

Understanding standard output and redirection is key to knowing why tee is useful—it lets you keep both the screen and file outputs.

2

Foundation

Basic output redirection and its limits

Concept: Explore how output redirection works and why it can hide output from the screen.

Using > or >> redirects output to a file but hides it from the screen. For example, ls > files.txt shows nothing on screen but saves output. This means you lose live feedback when running commands.

Result

No output appears on screen; output is only in files.txt.

Knowing this limitation sets the stage for why tee is needed to split output streams.

3

Intermediate

Using tee to split output streams

Concept: Learn how tee duplicates output to both screen and file simultaneously.

Run a command and pipe its output to tee: ls | tee files.txt. This shows the output on screen and saves it to files.txt at the same time. You can also append with tee -a to add to existing files.

Result

Output appears on screen and is saved in files.txt.

Understanding tee’s ability to split output helps you monitor commands live while keeping logs.

4

Intermediate

Appending output with tee -a option

🤔Before reading on: do you think tee overwrites or appends to files by default? Commit to your answer.

Concept: Discover how to add output to existing files without erasing previous content.

By default, tee overwrites files. Using tee -a appends output instead. For example: ls | tee -a files.txt adds new output to the end of files.txt without deleting old data.

Result

Output is added to the end of files.txt, preserving previous content.

Knowing how to append prevents accidental data loss when logging multiple command outputs.

5

Intermediate

Redirecting both stdout and stderr with tee

🤔Before reading on: do you think tee captures error messages (stderr) by default? Commit to your answer.

Concept: Learn how to capture both normal output and error messages using tee.

Commands can send output to stdout and errors to stderr. By default, tee only captures stdout. To capture both, use: command 2>&1 | tee file.txt. This redirects stderr to stdout, so tee saves both.

Result

Both output and error messages appear on screen and are saved in file.txt.

Understanding how to capture errors with tee is crucial for complete logging and debugging.

6

Advanced

Using tee in scripts for logging and monitoring

🤔Before reading on: do you think tee can be used inside scripts to log outputs while showing progress? Commit to your answer.

Concept: Apply tee in shell scripts to save logs without losing live output visibility.

In scripts, you can pipe commands to tee to save logs: some_command | tee output.log. This helps track script progress and errors in real time while keeping logs for later review.

Result

Script outputs appear live and are saved in output.log for auditing.

Knowing how to integrate tee in scripts improves troubleshooting and record keeping in automation.

7

Expert

Combining tee with process substitution and multiple files

🤔Before reading on: can tee write to multiple files and still show output on screen? Commit to your answer.

Concept: Explore advanced usage of tee to write output to several files and the screen simultaneously.

You can use tee with process substitution to write to multiple files: command | tee >(cat > file1.txt) >(cat > file2.txt). This sends output to both files and the screen. This technique is useful for complex logging setups.

Result

Output is visible on screen and saved in file1.txt and file2.txt simultaneously.

Understanding process substitution with tee unlocks powerful multi-target logging and monitoring.

Under the Hood

Tee reads input from the pipe or standard input and writes it simultaneously to standard output and one or more files. Internally, it uses system calls to duplicate the output stream, buffering data to ensure both destinations receive the same content without loss. It handles file opening, writing, and closing, managing append or overwrite modes as requested.

Why designed this way?

Tee was designed to solve the problem of losing live output when redirecting to files. Early Unix systems had simple redirection but no easy way to split output streams. Tee provides a simple, efficient way to duplicate output without complex scripting or multiple command runs, improving usability and debugging.

Input Stream
    │
    ▼
┌─────────┐
│   tee   │
├─────────┤
│  Write  │
│  to     │
│ Screen  │
│  and    │
│  Files  │
└─────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does tee capture error messages (stderr) by default? Commit to yes or no.

Common Belief: Tee captures all output including errors automatically.

Reality: Tee only captures standard output (stdout) by default. Error messages (stderr) must be redirected explicitly to be captured.

Why it matters: If you assume tee captures errors automatically, you might miss important error logs, leading to incomplete debugging information.

Quick: Does tee append to files by default or overwrite? Commit to your answer.

Common Belief: Tee appends output to files by default.

Reality: Tee overwrites files by default. You must use the -a option to append.

Why it matters: Assuming tee appends by default can cause accidental loss of previous log data.

Quick: Can tee write to multiple files at once without tricks? Commit to yes or no.

Common Belief: Tee can write to multiple files directly by listing them.

Reality: Tee writes to one or more files listed as arguments, but to write to multiple files and still see output on screen requires process substitution or multiple tee commands.

Why it matters: Misunderstanding this limits your ability to capture output efficiently in complex logging scenarios.

Quick: Does using tee slow down command execution significantly? Commit to yes or no.

Common Belief: Tee always causes noticeable slowdowns because it duplicates output.

Reality: Tee adds minimal overhead in most cases; any slowdown is usually negligible unless writing to slow storage or very large files.

Why it matters: Overestimating tee’s cost might discourage its use, missing out on its benefits for monitoring and logging.

Expert Zone

1

Tee buffers output internally, so very large outputs might appear delayed on screen until buffers flush.

2

When used in pipelines, tee can affect exit status propagation, so scripts must handle errors carefully.

3

Combining tee with process substitution allows complex multi-destination logging but can complicate error handling and resource cleanup.

When NOT to use

Avoid tee when you only need to save output without seeing it live; simple redirection is faster. For very high-performance logging, specialized logging tools or system-level tracing may be better. Also, tee is not suitable for binary data streams that require precise handling.

Production Patterns

In production, tee is often used in scripts to log outputs of long-running jobs while showing progress. It is combined with timestamping and log rotation. Advanced users chain multiple tees or use process substitution to split logs by severity or destination.

Connections

Unix Pipes and Redirection

Tee builds on the concept of pipes by splitting output streams instead of just passing them along.

Understanding pipes helps grasp how tee intercepts and duplicates data flows in shell commands.

Logging in Software Engineering

Tee is a simple tool for logging command outputs, similar to how software logs events for debugging and auditing.

Knowing tee’s role in logging connects command-line work to broader software reliability practices.

Water Distribution Systems

Tee’s output splitting is like water pipes splitting flow to multiple destinations.

Recognizing this physical analogy helps understand how data streams can be duplicated and routed.

Common Pitfalls

#1 Not capturing error messages with tee.

Wrong approach:

command | tee output.log

Correct approach:

command 2>&1 | tee output.log

Root cause:

Misunderstanding that stderr is separate from stdout and not captured by tee unless redirected.

#2 Overwriting logs unintentionally when appending was needed.

Wrong approach:

command | tee output.log

Correct approach:

command | tee -a output.log

Root cause:

Assuming tee appends by default instead of overwriting files.

#3 Trying to write to multiple files without process substitution.

Wrong approach:

command | tee file1.txt file2.txt

Correct approach:

command | tee >(cat > file1.txt) >(cat > file2.txt)

Root cause:

Not knowing tee can only write to multiple files with process substitution or multiple commands.

Key Takeaways

Tee duplicates command output so you can see it live and save it to files simultaneously.

By default, tee overwrites files and only captures standard output, not errors.

Using tee with the -a option appends output to files, preventing data loss.

Redirecting stderr to stdout is necessary to capture error messages with tee.

Advanced usage of tee with process substitution allows writing to multiple files at once.