PIPE: Add pipe support for passing data into and out of terminal commands by ficocelliguy · Pull Request #2525 · bitburner-official/bitburner-src

ficocelliguy · 2026-02-22T19:31:37Z

A number of players have asked for support for pipes in the terminal, or have been confused as to its lack of support:
https://discord.com/channels/415207508303544321/415207839246581781/1411811521935315016
https://discord.com/channels/415207508303544321/415207839246581781/1275557408726323260
https://discord.com/channels/415207508303544321/415207508303544323/932487013922390016
https://discord.com/channels/415207508303544321/415207508303544323/933463698431967283
https://discord.com/channels/415207508303544321/415207508303544323/573291980801703946

So, I've added support for them!

Deployed and testable at:
https://ficocelliguy.github.io/bitburner-src-2/

Features (and test cases):

echo command added
piping to text file support added - will overwrite if > is used, otherwise will append ( >> )

echo test;
echo test data > newFile.txt;
echo overwrite that data > newFile.txt;

support for grepping string literals added
Support for passing pipe output as additional args for any terminal command added
support for multiple pipes in a chain added

echo Hello World > newFile.txt;
ls | grep .txt;
ls | grep .txt > fileList.txt;

new ns property stdin added: it is a port handle that receives any data passed to the script via pipes
Support for piping to write the contents of script JS files added
Support for piping script terminal output to another output location added

echo "export function main(ns) { ns.tprint('Input received: ', ns.stdin.read() ); }" > myScript.js;
echo arg1 arg2 | myScript.js;
echo arg3 arg4 | myScript.js > newLogFile.txt;

piping from tail output into additional sources added

run myScript arg1; tail myScript arg1 >> tailLogFile.txt;

… on string literals

…pts with piped arguments as input

…ns once per >

… game is restarted

… react warning form updating terminal after a command that causes navigation

…cts.md Co-authored-by: David Walker <d0sboots@gmail.com>

…d in the terminal (excluding long-running processes)

…ner-src into pipe_support

…ntAndBypassPipes in places where the content isn't intended to be piped

…instead of Terminal.error

d0sboots

I'm gonna have to review the whole thing from the top aren't I 😭

d0sboots · 2026-06-14T05:20:55Z


 ```
-[home /]> echo test123 >> newFile.txt
+[home /]> cat < myfile.txt | cat


I would use your grep example from above here, to show how < can be used to avoid needing a pipe.
grep "error" < myfile.txt

I get that you want to show the "only first" property, so maybe it can be "in addition to" instead of replacing.

d0sboots · 2026-06-14T05:23:39Z

+
+### Semicolons: `;`
+
+Semicolons let you run multiple independent commands on one line. Each command is separate — they do not share pipes or redirects.


I'd add something about sequencing here. Specifically, in Bitburner (unlike in unix), each command runs in parallel IIRC, and this is noticable if you try to do hack;hack.

long-running commands are awaited one at a time when separated by semicolons in dev currently, afaik as a result of the TerminalAction changes you recently worked on

d0sboots · 2026-06-14T05:27:50Z

+
+### Piping into scripts
+
+When a script is part of a pipe chain, it can read from stdin using `ns.getStdin()`. The script receives whatever the previous command wrote to stdout.


Just say "the terminal" instead of stdout, it's clearer in our case.

"read from the terminal" is what current grep -p does, unlike getStdin. stdin isn't the visible terminal broadly, but only data piped in from an output redirect of some sort. I've re-worded this to try to improve the clarity.

d0sboots · 2026-06-14T05:41:22Z

 export function commonEditor(command: string, { args, server, vim }: EditorParameters, allowZeroFiles = false): void {
  if (args.length < 1 && !allowZeroFiles) {
-    return Terminal.fatal(`Incorrect usage of ${command} command. Usage: ${command} [scriptname]`);
+    return Terminal.error(`Incorrect usage of ${command} command. Usage: ${command} [scriptname]`, getTerminalStdIO());


What is your logic for turning these, and things like these, back to error?

fatal explicitly closes the provided stdIO. For places where that didn't seem important, I used error. I can use whichever you think makes sense, though, for things like this.

d0sboots · 2026-06-14T05:42:23Z

-  if (args.length !== 0) return Terminal.fatal("Incorrect usage of hack command. Usage: hack");
-  if (server.purchasedByPlayer) return Terminal.fatal("Cannot hack your own machines!");
-  if (!server.hasAdminRights) return Terminal.fatal("You do not have admin rights for this machine!");
+  if (args.length !== 0) return Terminal.fatal("Incorrect usage of hack command. Usage: hack", stdIO);


I thought the whole point of fatal was that it didn't need this extra argument?

fatal is used to close the StdIO, as opposed to error which just logs red text. There are only a handful of places where there isn't a StdIO already. More importantly, I kept running into places that missed passing the StdIO to fatal after the big merge conflict resolution, so it seemed more future-proof to require it.

d0sboots · 2026-06-14T05:48:08Z

+    }
+    const handle = new PortHandle(stdinHandle.n);
+    // Provide only the methods the player needs to access (or write to) stdio
+    return {


This creates a new set of closures for every handle. We definitely want to be returning a class instead. If PortHandle isn't that class for some reason, then we should make a new one - but my impression was that PortHandle was that class.

PortHandle is a class. I did this to avoid exposing the port number (which are not valid for player use cases.) if a player did something like ns.peek(ns.getStdin().n) it would throw an error about port numbers needing to be positive.

I could make a new class to do something similar, exposing only the relevant methods? or maybe I can just ignore this odd use case?

ficocelliguy added 30 commits September 28, 2025 13:40

Support grepping string literals

dcc0075

Pipe groundwork

70e9ea1

Pipe to file support

df5b6ce

Pipe to grep and other commands support

6de1cc6

Chains of pipes support

0e141ae

Chains of pipes support

a286cee

support filtering matching lines and maintaining line numbers in grep…

77ff2ae

… on string literals

support appending vs overwriting based on pipe type

99ec76d

support writing/appending to script files

4039d1e

Support for cat as pipe input

1b0ee42

groundwork for script pipe output

1e59c76

PIPE: support piping from scripts; centralize pipe config

e5e560b

PIPE: support piping from scripts; centralize pipe config

abbd3a4

Pipe support: initial unit tests

6081890

Pipe support: handle multiple commands with distinct pipes

42441ac

Pipe support: unit tests for piping to script file and launching scri…

bb2b923

…pts with piped arguments as input

Pipe support: unit tests for piping from a script

0a69b60

Pipe support: unit tests for cat; ensure overwriting files only happe…

2801318

…ns once per >

Pipe support: unit tests and fixes for script pipes

81af8a9

Pipe support: support piping out of tail command

eb97b7d

Pipe support: fix unit tests

863a350

Merge remote-tracking branch 'upstream/dev' into pipe_support

3f9ac9f

Merge remote-tracking branch 'upstream/dev' into pipe_support

0f1e60d

PIPES: add ns.stdIn and push all piped input to that port handle

2445f0e

Merge remote-tracking branch 'upstream/dev' into pipe_support

b66f255

Fix unit test

503ae0c

Add pipe into cat

d65cf06

Fix piping from one script to another; support re-linking pipes after…

d80eebf

… game is restarted

Fix unit tests

e2d189c

fix stdin case

e0eb983

ficocelliguy and others added 21 commits February 18, 2026 19:48

Pipes: WIP docs page placeholder

fbfcbea

linting my documentation markdown file, apparently? ugh

77c0439

Fix tail log output redirect

509b3ab

Add handling for invalid filenames, remove dile path typecasting; fix…

1c47c06

… react warning form updating terminal after a command that causes navigation

Update src/Documentation/doc/en/programming/terminal_pipes_and_redire…

ccb0aa5

…cts.md Co-authored-by: David Walker <d0sboots@gmail.com>

Update src/Documentation/doc/en/programming/terminal_pipes_and_redire…

ac40c7f

…cts.md Co-authored-by: David Walker <d0sboots@gmail.com>

Update src/Documentation/doc/en/programming/terminal_pipes_and_redire…

22c8171

…cts.md Co-authored-by: David Walker <d0sboots@gmail.com>

Merge branch 'dev' into pipe_support

e7b0089

Move "Terminal Pipes and Redirects" to above pages in advanced/*.md

3790904

Add missing usages of stdIO in src\Programs\Programs.ts

7c42b01

Wait for pipes to close before executing the next ;-delineated comman…

23f78ce

…d in the terminal (excluding long-running processes)

Merge branch 'pipe_support' of https://github.com/ficocelliguy/bitbur…

32ca1f3

…ner-src into pipe_support

Remove default stdio in Terminal.print and similar; expressly use pri…

a92cc69

…ntAndBypassPipes in places where the content isn't intended to be piped

Merge remote-tracking branch 'upstream/dev' into pipe_support

bf4f264

Gracefully handle blocking terminal commands

51da6c4

Update pipe documentation

b99ba19

Use Terminal.fatal when a process is exiting and closing its stdout, …

4d6ac42

…instead of Terminal.error

Merging in dev

cbdba17

Bugfixes

57b8839

bigfix

5c754b0

more clarity improvements and edge case hardening

e40d181

d0sboots reviewed Jun 14, 2026

View reviewed changes

ficocelliguy added 6 commits June 14, 2026 10:40

PR feedback

701a218

Merge remote-tracking branch 'upstream/dev' into pipe_support

53b5c93

Handle stdio cancellation in Terminal

bf7ee9c

Handle long-running commands inside pipe chains

5499594

Better handle cat and grep; handle misplaced leading input redirection <

6fe7dc0

Add unit tests

9dbaa22

ficocelliguy mentioned this pull request Jun 28, 2026

UI: Add support for cat printing to terminal #2921

Closed

Merge remote-tracking branch 'upstream/dev' into pipe_support

d0b78a1


		### Semicolons: `;`

		Semicolons let you run multiple independent commands on one line. Each command is separate — they do not share pipes or redirects.


		### Piping into scripts

		When a script is part of a pipe chain, it can read from stdin using `ns.getStdin()`. The script receives whatever the previous command wrote to stdout.

Uh oh!

Conversation

ficocelliguy commented Feb 22, 2026

Uh oh!

d0sboots left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ficocelliguy Jun 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ficocelliguy Jun 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ficocelliguy Jun 14, 2026 •

edited

Loading

ficocelliguy Jun 14, 2026 •

edited

Loading