Repository: nushell/nushell.github.io
Pull request #1826: Add docs for jobs
Author: login: cosineblast
Created: 2025-03-03T19:31:19Z | Merged: 2025-03-30T21:29:16Z

This adds a book entry for background job handling in nushell, with regard to how it is currently implemented.

Quick question: How do I generate the `.md` files for new commands such as `job spawn`?


Diff:
diff --git a/book/background_jobs.md b/book/background_jobs.md
new file mode 100644
index 00000000000..2f5828de7ff
--- /dev/null
+++ b/book/background_jobs.md
@@ -0,0 +1,107 @@
+# Background Jobs
+
+Nushell currently has experimental support for thread-based background jobs.
+
+## Spawning Jobs
+
+Jobs can be can be spawned using [`job spawn`](/commands/docs/job_spawn.md), which receives a closure and starts its execution in a background thread, returning
+an unique integer id for the spawned job:
+
+```nu
+'i am' | save status.txt
+
+job spawn { sleep 10sec; ' inevitable' | save --append status.txt }
+# => 1
+
+open status.txt
+# => i am
+
+# wait for 10 seconds
+sleep 10sec
+
+open status.txt
+# => i am inevitable
+```
+
+## Listing and Killing jobs
+
+Active jobs can be queried with the [`job list`](/commands/docs/job_list.md) command, which returns a table with the information of the jobs which are currently executing.
+Jobs can also be killed/interrupted by using the [`job kill`](/commands/docs/job_kill.md) command, which interrupts the job's thread and kills all of the job's child processes:
+
+```nu
+let id = job spawn { sleep 1day }
+
+job list
+# => ┏━━━┳━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━┓
+# => ┃ # ┃ id ┃  type  ┃      pids      ┃
+# => ┣━━━╋━━━━╋━━━━━━━━╋━━━━━━━━━━━━━━━━┫
+# => ┃ 0 ┃  1 ┃ thread ┃ [list 0 items] ┃
+# => ┗━━━┻━━━━┻━━━━━━━━┻━━━━━━━━━━━━━━━━┛
+
+job kill $id
+
+job list
+# => ╭────────────╮
+# => │ empty list │
+# => ╰────────────╯
+```
+
+## Job suspension
+
+On Unix targets, such as Linux and macOS, Nushell also supports suspending external commands using <kbd>Ctrl</kbd>+<kbd>Z</kbd>. When a running process is suspended, it is turned into a "frozen" background job:
+
+```nu
+long_running_process # this starts running, then Ctrl+Z is pressed
+# => Job 1 is frozen
+
+job list
+# => ┏━━━┳━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━┓
+# => ┃ # ┃ id ┃  type  ┃      pids      ┃
+# => ┣━━━╋━━━━╋━━━━━━━━╋━━━━━━━━━━━━━━━━┫
+# => ┃ 0 ┃  1 ┃ frozen ┃ [list 1 items] ┃
+# => ┗━━━┻━━━━┻━━━━━━━━┻━━━━━━━━━━━━━━━━┛
+```
+
+A frozen job can be brought back into foreground with the [`job unfreeze`](/commands/docs/job_unfreeze.md) command:
+
+```nu
+job unfreeze
+# process is brought back where it stopped
+```
+
+::: tip Tip
+For those familiar with other Unix shells, you can create an alias to emulate the behavior of the `fg` command:
+
+```nu
+alias fg = job unfreeze
+```
+
+:::
+
+By default, `job unfreeze` will unfreeze the most recently frozen job. However, you can also specify the id of a specific job to unfreeze:
+
+```nu
+vim
+# => Job 1 is frozen
+
+long_running_process
+# => Job 2 is frozen
+
+job unfreeze 1
+# we're back in vim
+```
+
+## Exit Behavior
+
+Unlike many other shells, Nushell jobs are **not** separate processes,
+and are instead implemented as background threads.
+
+An important side effect of this, is that all background jobs will terminate once the shell
+process exits.
+For this reason, Nushell has no UNIX-like `disown` command to prevent jobs from terminating once the shell exits.
+To account for that, there are plans for a `job dispatch` implementation in the future,
+for spawning independent background processes.
+
+Additionally, if the user is running an interactive Nushell session and runs
+[`exit`](/commands/docs/exit.md) while there are background jobs running,
+the shell will warn about them before prompting the user to confirm `exit`.
diff --git a/book/background_task.md b/book/background_task.md
deleted file mode 100644
index e99b2581361..00000000000
--- a/book/background_task.md
+++ /dev/null
@@ -1,34 +0,0 @@
-# Background Tasks with Nu
-
-Currently, Nushell doesn't have built-in background task management feature, but you can make it "support" background task with some tools, here are some examples:
-
-1. Using a third-party task management tools, like [pueue](https://github.com/Nukesor/pueue)
-2. Using a terminal multiplexer, like [tmux](https://github.com/tmux/tmux/wiki) or [zellij](https://zellij.dev/)
-
-## Using Nu With Pueue
-
-The module borrows the power of [pueue](https://github.com/Nukesor/pueue), it is possible to schedule background tasks to pueue, and manage those tasks (such as viewing logs, killing tasks, or getting the running status of all tasks, creating groups, pausing tasks etc etc)
-
-Unlike terminal multiplexer, you don't need to attach to multiple tmux sessions, and get task status easily.
-
-Here we provide a [nushell module](https://github.com/nushell/nu_scripts/tree/main/modules/background_task) that makes working with pueue easier.
-
-Here is a setup example to make Nushell "support" background tasks:
-
-1. Install pueue
-2. run `pueued`, you can refer to [start-the-daemon page](https://github.com/Nukesor/pueue/wiki/Get-started#start-the-daemon) for more information.
-3. Put the [task.nu](https://github.com/nushell/nu_scripts/blob/main/modules/background_task/task.nu) file under `$env.NU_LIB_DIRS`.
-4. Add a line to the `$nu.config-path` file: `use task.nu`
-5. Restart Nushell.
-
-Then you will get some commands to schedule background tasks. (e.g: `task spawn`, `task status`, `task log`)
-
-Cons: It spawns a new Nushell interpreter to execute every single task, so it doesn't inherit current scope's variables, custom commands, alias definition.
-It only inherits environment variables whose value can be converted to a string.
-Therefore, if you want to use custom commands or variables, you have to [`use`](/commands/docs/use.md) or [`def`](/commands/docs/def.md) them within the given block.
-
-## Using Nu With Terminal Multiplexer
-
-You can choose and install a terminal multiplexer and use it.
-
-It allows you to easily switch between multiple programs in one terminal, detach them (they continue to run in the background) and reconnect them to a different terminal.  As a result, it is very flexible and usable.
diff --git a/book/nu_as_a_shell.md b/book/nu_as_a_shell.md
index 7f457ac9072..4b31e6c04e3 100644
--- a/book/nu_as_a_shell.md
+++ b/book/nu_as_a_shell.md
@@ -23,6 +23,6 @@ It is also possible to define [custom signatures for external commands](externs.
 
 [Coloring and Theming in Nu](coloring_and_theming.md) goes into more detail about how to configure Nushell's appearance.
 
-If you want to schedule some commands to run in the background, [Background task in Nu](background_task.md) provides simple guidelines for you to follow.
+If you want to schedule some commands to run in the background, [Background jobs](background_jobs.md) provides simple guidelines for you to follow.
 
 Finally, [hooks](hooks.md) allow you to insert fragments of Nushell code to run at certain events.
diff --git a/de/book/background_task.md b/de/book/background_jobs.md
similarity index 99%
rename from de/book/background_task.md
rename to de/book/background_jobs.md
index 0c89c6bddfd..1e1b764f74b 100644
--- a/de/book/background_task.md
+++ b/de/book/background_jobs.md
@@ -17,6 +17,7 @@ Den Status von Tasks erhält man sehr einfach.
 Hier ein einfaches Beispiel wie ein [nushell module](https://github.com/nushell/nu_scripts/tree/main/background_task) mit pueu zusammenarbeitet.
 
 Das Setup umfasst:
+
 1. installiere pueue
 2. führe `pueued` mit der default Konfiguration aus. Siehe unter [start-the-daemon page](https://github.com/Nukesor/pueue/wiki/Get-started#start-the-daemon) für mehr Informationen.
 3. speichere die [job.nu](https://github.com/nushell/nu_scripts/blob/main/modules/background_task/job.nu) Datei unter `$env.NU_LIB_DIRS`.
diff --git a/de/book/nu_as_a_shell.md b/de/book/nu_as_a_shell.md
index 8357c8c3c13..b3605767f89 100644
--- a/de/book/nu_as_a_shell.md
+++ b/de/book/nu_as_a_shell.md
@@ -25,6 +25,6 @@ Es ist auch möglich, eigene [Signaturen für externe Befehle (EN)](/book/extern
 
 [Farben und Themen in Nu](coloring_and_theming.md)) geht ins Detail zum Thema, wie Nushells Aussehen konfiguriert werden kann.
 
-Sind einige Befehle geplant , die im Hintergrund ablaufen sollen, so kann darüber in [Hintergrund Tasks in Nu](background_task.md) nachgelesen werden.
+Sind einige Befehle geplant , die im Hintergrund ablaufen sollen, so kann darüber in [Hintergrund Tasks in Nu](background_jobs.md) nachgelesen werden.
 
 Schliesslich erklärt [Hooks](hooks.md) wie Fragmente von Nushell Code beim Auftreten gewisser Ereignisse ausgeführt werden kann.
diff --git a/tools/i18n-meta.json b/tools/i18n-meta.json
index 0bc38df95ba..0c6f4151ec7 100644
--- a/tools/i18n-meta.json
+++ b/tools/i18n-meta.json
@@ -48,7 +48,7 @@
     "ru": "-"
   },
   {
-    "name": "background_task.md",
+    "name": "background_jobs.md",
     "en": "In progress",
     "zh-CN": "-",
     "fr": "-",


Reviews:
user: login: 132ikl
body: thanks for writing this up! sorry I just got around to this, I completely forgot about this one :sweat_smile: 

i have a few suggestions, let me know what you think
state: CHANGES_REQUESTED
author_association: MEMBER
submitted_at: 2025-03-20T02:36:16Z
user: login: cosineblast
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-29T19:51:38Z

Review comments:
diff_hunk: @@ -1,34 +1,77 @@
-# Background Tasks with Nu
+# Background Jobs
 
-Currently, Nushell doesn't have built-in background task management feature, but you can make it "support" background task with some tools, here are some examples:
+## Spawning Jobs
 
-1. Using a third-party task management tools, like [pueue](https://github.com/Nukesor/pueue)
-2. Using a terminal multiplexer, like [tmux](https://github.com/tmux/tmux/wiki) or [zellij](https://zellij.dev/)
+Nushell currently presents experimental support for thread-based background jobs.
path: book/background_task.md
user: login: 132ikl
body: could you move this line to above the "Spawning Jobs" header?

also, nitpick, but not sure about "presents" here, I think just "has" works fine
created_at: 2025-03-20T02:06:33Z
author_association: MEMBER
diff_hunk: @@ -1,34 +1,77 @@
-# Background Tasks with Nu
+# Background Jobs
 
-Currently, Nushell doesn't have built-in background task management feature, but you can make it "support" background task with some tools, here are some examples:
+## Spawning Jobs
 
-1. Using a third-party task management tools, like [pueue](https://github.com/Nukesor/pueue)
-2. Using a terminal multiplexer, like [tmux](https://github.com/tmux/tmux/wiki) or [zellij](https://zellij.dev/)
+Nushell currently presents experimental support for thread-based background jobs.
 
-## Using Nu With Pueue
+Jobs can be can be spawned using [`job spawn`](/commands/docs/job_spawn.md), which receives a closure and starts its execution in a background thread, returning
+an unique integer id for such job:
 
-The module borrows the power of [pueue](https://github.com/Nukesor/pueue), it is possible to schedule background tasks to pueue, and manage those tasks (such as viewing logs, killing tasks, or getting the running status of all tasks, creating groups, pausing tasks etc etc)
+```nu
+'i am' | save status.txt
 
-Unlike terminal multiplexer, you don't need to attach to multiple tmux sessions, and get task status easily.
+job spawn { sleep 10sec; ' inevitable' | save --append status.txt }
+## => 1
 
-Here we provide a [nushell module](https://github.com/nushell/nu_scripts/tree/main/modules/background_task) that makes working with pueue easier.
+open status.txt
+## => i am
 
-Here is a setup example to make Nushell "support" background tasks:
+# wait for 10 seconds
+sleep 10sec
 
-1. Install pueue
-2. run `pueued`, you can refer to [start-the-daemon page](https://github.com/Nukesor/pueue/wiki/Get-started#start-the-daemon) for more information.
-3. Put the [task.nu](https://github.com/nushell/nu_scripts/blob/main/modules/background_task/task.nu) file under `$env.NU_LIB_DIRS`.
-4. Add a line to the `$nu.config-path` file: `use task.nu`
-5. Restart Nushell.
+open status.txt
+## => i am inevitable
+```
 
-Then you will get some commands to schedule background tasks. (e.g: `task spawn`, `task status`, `task log`)
+::: tip Note
+Unlike many other shells, Nushell jobs are **not** separate processes, and are instead implemented
+as background threads. An important side effect of that, is that all background jobs terminate once the shell process exits.
+:::
path: book/background_task.md
user: login: 132ikl
body: could you expand this into a proper (but brief) section? things I think we should specifically cover:

- interactive vs. non-interactive job killing behavior on Nushell exit
- explain that this is the rationale behind no `disown` / eventually `job dispatch`
created_at: 2025-03-20T02:10:15Z
author_association: MEMBER
diff_hunk: @@ -1,34 +1,77 @@
-# Background Tasks with Nu
+# Background Jobs
 
-Currently, Nushell doesn't have built-in background task management feature, but you can make it "support" background task with some tools, here are some examples:
+## Spawning Jobs
 
-1. Using a third-party task management tools, like [pueue](https://github.com/Nukesor/pueue)
-2. Using a terminal multiplexer, like [tmux](https://github.com/tmux/tmux/wiki) or [zellij](https://zellij.dev/)
+Nushell currently presents experimental support for thread-based background jobs.
 
-## Using Nu With Pueue
+Jobs can be can be spawned using [`job spawn`](/commands/docs/job_spawn.md), which receives a closure and starts its execution in a background thread, returning
+an unique integer id for such job:
 
-The module borrows the power of [pueue](https://github.com/Nukesor/pueue), it is possible to schedule background tasks to pueue, and manage those tasks (such as viewing logs, killing tasks, or getting the running status of all tasks, creating groups, pausing tasks etc etc)
+```nu
+'i am' | save status.txt
 
-Unlike terminal multiplexer, you don't need to attach to multiple tmux sessions, and get task status easily.
+job spawn { sleep 10sec; ' inevitable' | save --append status.txt }
+## => 1
 
-Here we provide a [nushell module](https://github.com/nushell/nu_scripts/tree/main/modules/background_task) that makes working with pueue easier.
+open status.txt
+## => i am
 
-Here is a setup example to make Nushell "support" background tasks:
+# wait for 10 seconds
+sleep 10sec
 
-1. Install pueue
-2. run `pueued`, you can refer to [start-the-daemon page](https://github.com/Nukesor/pueue/wiki/Get-started#start-the-daemon) for more information.
-3. Put the [task.nu](https://github.com/nushell/nu_scripts/blob/main/modules/background_task/task.nu) file under `$env.NU_LIB_DIRS`.
-4. Add a line to the `$nu.config-path` file: `use task.nu`
-5. Restart Nushell.
+open status.txt
+## => i am inevitable
+```
 
-Then you will get some commands to schedule background tasks. (e.g: `task spawn`, `task status`, `task log`)
+::: tip Note
+Unlike many other shells, Nushell jobs are **not** separate processes, and are instead implemented
+as background threads. An important side effect of that, is that all background jobs terminate once the shell process exits.
+:::
 
-Cons: It spawns a new Nushell interpreter to execute every single task, so it doesn't inherit current scope's variables, custom commands, alias definition.
-It only inherits environment variables whose value can be converted to a string.
-Therefore, if you want to use custom commands or variables, you have to [`use`](/commands/docs/use.md) or [`def`](/commands/docs/def.md) them within the given block.
+## Listing and Killing jobs
 
-## Using Nu With Terminal Multiplexer
+Active jobs can be queried with the [`job list`](/commands/docs/job_list.md) command, which returns a table with the information of the jobs which are currently executing.
+Jobs can also be kiled/interrupted by using the [`job kill`](/commands/docs/job_kill.md) command, which interrupts the job's thread and kills all of the job's child processes:
path: book/background_task.md
user: login: 132ikl
body: ```suggestion
Jobs can also be killed/interrupted by using the [`job kill`](/commands/docs/job_kill.md) command, which interrupts the job's thread and kills all of the job's child processes:
```
created_at: 2025-03-20T02:12:08Z
author_association: MEMBER
diff_hunk: @@ -1,34 +1,77 @@
-# Background Tasks with Nu
+# Background Jobs
 
-Currently, Nushell doesn't have built-in background task management feature, but you can make it "support" background task with some tools, here are some examples:
+## Spawning Jobs
 
-1. Using a third-party task management tools, like [pueue](https://github.com/Nukesor/pueue)
-2. Using a terminal multiplexer, like [tmux](https://github.com/tmux/tmux/wiki) or [zellij](https://zellij.dev/)
+Nushell currently presents experimental support for thread-based background jobs.
 
-## Using Nu With Pueue
+Jobs can be can be spawned using [`job spawn`](/commands/docs/job_spawn.md), which receives a closure and starts its execution in a background thread, returning
+an unique integer id for such job:
 
-The module borrows the power of [pueue](https://github.com/Nukesor/pueue), it is possible to schedule background tasks to pueue, and manage those tasks (such as viewing logs, killing tasks, or getting the running status of all tasks, creating groups, pausing tasks etc etc)
+```nu
+'i am' | save status.txt
 
-Unlike terminal multiplexer, you don't need to attach to multiple tmux sessions, and get task status easily.
+job spawn { sleep 10sec; ' inevitable' | save --append status.txt }
+## => 1
 
-Here we provide a [nushell module](https://github.com/nushell/nu_scripts/tree/main/modules/background_task) that makes working with pueue easier.
+open status.txt
+## => i am
 
-Here is a setup example to make Nushell "support" background tasks:
+# wait for 10 seconds
+sleep 10sec
 
-1. Install pueue
-2. run `pueued`, you can refer to [start-the-daemon page](https://github.com/Nukesor/pueue/wiki/Get-started#start-the-daemon) for more information.
-3. Put the [task.nu](https://github.com/nushell/nu_scripts/blob/main/modules/background_task/task.nu) file under `$env.NU_LIB_DIRS`.
-4. Add a line to the `$nu.config-path` file: `use task.nu`
-5. Restart Nushell.
+open status.txt
+## => i am inevitable
+```
 
-Then you will get some commands to schedule background tasks. (e.g: `task spawn`, `task status`, `task log`)
+::: tip Note
+Unlike many other shells, Nushell jobs are **not** separate processes, and are instead implemented
+as background threads. An important side effect of that, is that all background jobs terminate once the shell process exits.
+:::
 
-Cons: It spawns a new Nushell interpreter to execute every single task, so it doesn't inherit current scope's variables, custom commands, alias definition.
-It only inherits environment variables whose value can be converted to a string.
-Therefore, if you want to use custom commands or variables, you have to [`use`](/commands/docs/use.md) or [`def`](/commands/docs/def.md) them within the given block.
+## Listing and Killing jobs
 
-## Using Nu With Terminal Multiplexer
+Active jobs can be queried with the [`job list`](/commands/docs/job_list.md) command, which returns a table with the information of the jobs which are currently executing.
+Jobs can also be kiled/interrupted by using the [`job kill`](/commands/docs/job_kill.md) command, which interrupts the job's thread and kills all of the job's child processes:
 
-You can choose and install a terminal multiplexer and use it.
+```nu
+let id = job spawn { sleep 1day }
 
-It allows you to easily switch between multiple programs in one terminal, detach them (they continue to run in the background) and reconnect them to a different terminal.  As a result, it is very flexible and usable.
+job list
+# => ┏━━━┳━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━┓
+# => ┃ # ┃ id ┃  type  ┃      pids      ┃
+# => ┣━━━╋━━━━╋━━━━━━━━╋━━━━━━━━━━━━━━━━┫
+# => ┃ 0 ┃  1 ┃ thread ┃ [list 0 items] ┃
+# => ┗━━━┻━━━━┻━━━━━━━━┻━━━━━━━━━━━━━━━━┛
+
+job kill $id
+
+job list
+# => ╭────────────╮
+# => │ empty list │
+# => ╰────────────╯
+```
+
+## Unix Ctrl-Z
+
+In unix targets (namely Linux and MacOS), Nushell's background job support also integrates with the Ctrl-Z feature
+of terminals (more specifically, the `SIGTSTP` signal), which allows users to suspend foreground processes into background jobs.
+When a running process is suspended, it is turned into a background job of type `frozen`. A frozen job can be reanimated into foreground with the
+[`job unfreeze`](/commands/docs/job_unfreeze.md) command.
+
+```
+long_running_process
+# (Ctrl-Z is pressed)
+
+job list
+# => ┏━━━┳━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━┓
+# => ┃ # ┃ id ┃  type  ┃      pids      ┃
+# => ┣━━━╋━━━━╋━━━━━━━━╋━━━━━━━━━━━━━━━━┫
+# => ┃ 0 ┃  1 ┃ frozen ┃ [list 1 items] ┃
+# => ┗━━━┻━━━━┻━━━━━━━━┻━━━━━━━━━━━━━━━━┛
+
+job unfreeze 1
+# (process is brought back where it stopped)
+```
+
+If no job id is provided to `job unfreeze`, it will unfreeze the job id of the most recently frozen job.
+Therefore, one can use `alias fg = job unfreeze` to achieve a behavior similar to the one of existing unix shells.
path: book/background_task.md
user: login: 132ikl
body: ````suggestion
## Job suspension

On Unix targets, such as Linux and macOS, Nushell also supports suspending external commands using <kbd>Ctrl</kbd>+<kbd>Z</kbd>. When a running process is suspended, it is turned into a "frozen" background job: 

```nu
long_running_process # this starts running, then Ctrl+Z is pressed
# => Job 1 is frozen

job list
# => ┏━━━┳━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━┓
# => ┃ # ┃ id ┃  type  ┃      pids      ┃
# => ┣━━━╋━━━━╋━━━━━━━━╋━━━━━━━━━━━━━━━━┫
# => ┃ 0 ┃  1 ┃ frozen ┃ [list 1 items] ┃
# => ┗━━━┻━━━━┻━━━━━━━━┻━━━━━━━━━━━━━━━━┛
```


A frozen job can be brought back into foreground with the [`job unfreeze`](/commands/docs/job_unfreeze.md) command:


```nu
job unfreeze
# process is brought back where it stopped
```

::: tip Tip
For those familiar with other Unix shells, you can create an alias to emulate the behavior of the `fg` command:
```nu
alias fg = job unfreeze
```
:::

By default, `job unfreeze` will unfreeze the most recently frozen job. However, you can also specify the id of a specific job to unfreeze:

```nu
vim
# => Job 1 is frozen

long_running_process
# => Job 2 is frozen

job unfreeze 1
# we're back in vim
```
````

I tweaked this section to make it flow better, let me know what you think. 

I'm not sure if we need to specify SIGTSTP specifically, I thought of moving it to a note/tip but I couldn't think of what that would look like.
created_at: 2025-03-20T02:33:12Z
author_association: MEMBER
path: book/background_task.md
user: login: 132ikl
body: could we rename the file to `background_jobs.md` also?
created_at: 2025-03-20T02:33:46Z
author_association: MEMBER
diff_hunk: @@ -1,34 +1,77 @@
-# Background Tasks with Nu
+# Background Jobs
 
-Currently, Nushell doesn't have built-in background task management feature, but you can make it "support" background task with some tools, here are some examples:
+## Spawning Jobs
 
-1. Using a third-party task management tools, like [pueue](https://github.com/Nukesor/pueue)
-2. Using a terminal multiplexer, like [tmux](https://github.com/tmux/tmux/wiki) or [zellij](https://zellij.dev/)
+Nushell currently presents experimental support for thread-based background jobs.
 
-## Using Nu With Pueue
+Jobs can be can be spawned using [`job spawn`](/commands/docs/job_spawn.md), which receives a closure and starts its execution in a background thread, returning
+an unique integer id for such job:
 
-The module borrows the power of [pueue](https://github.com/Nukesor/pueue), it is possible to schedule background tasks to pueue, and manage those tasks (such as viewing logs, killing tasks, or getting the running status of all tasks, creating groups, pausing tasks etc etc)
+```nu
+'i am' | save status.txt
 
-Unlike terminal multiplexer, you don't need to attach to multiple tmux sessions, and get task status easily.
+job spawn { sleep 10sec; ' inevitable' | save --append status.txt }
+## => 1
path: book/background_task.md
user: login: 132ikl
body: ```suggestion
# => 1
```
created_at: 2025-03-20T02:34:14Z
author_association: MEMBER
diff_hunk: @@ -1,34 +1,77 @@
-# Background Tasks with Nu
+# Background Jobs
 
-Currently, Nushell doesn't have built-in background task management feature, but you can make it "support" background task with some tools, here are some examples:
+## Spawning Jobs
 
-1. Using a third-party task management tools, like [pueue](https://github.com/Nukesor/pueue)
-2. Using a terminal multiplexer, like [tmux](https://github.com/tmux/tmux/wiki) or [zellij](https://zellij.dev/)
+Nushell currently presents experimental support for thread-based background jobs.
 
-## Using Nu With Pueue
+Jobs can be can be spawned using [`job spawn`](/commands/docs/job_spawn.md), which receives a closure and starts its execution in a background thread, returning
+an unique integer id for such job:
 
-The module borrows the power of [pueue](https://github.com/Nukesor/pueue), it is possible to schedule background tasks to pueue, and manage those tasks (such as viewing logs, killing tasks, or getting the running status of all tasks, creating groups, pausing tasks etc etc)
+```nu
+'i am' | save status.txt
 
-Unlike terminal multiplexer, you don't need to attach to multiple tmux sessions, and get task status easily.
+job spawn { sleep 10sec; ' inevitable' | save --append status.txt }
+## => 1
 
-Here we provide a [nushell module](https://github.com/nushell/nu_scripts/tree/main/modules/background_task) that makes working with pueue easier.
+open status.txt
+## => i am
path: book/background_task.md
user: login: 132ikl
body: ```suggestion
# => i am
```
created_at: 2025-03-20T02:34:18Z
author_association: MEMBER
diff_hunk: @@ -1,34 +1,77 @@
-# Background Tasks with Nu
+# Background Jobs
 
-Currently, Nushell doesn't have built-in background task management feature, but you can make it "support" background task with some tools, here are some examples:
+## Spawning Jobs
 
-1. Using a third-party task management tools, like [pueue](https://github.com/Nukesor/pueue)
-2. Using a terminal multiplexer, like [tmux](https://github.com/tmux/tmux/wiki) or [zellij](https://zellij.dev/)
+Nushell currently presents experimental support for thread-based background jobs.
 
-## Using Nu With Pueue
+Jobs can be can be spawned using [`job spawn`](/commands/docs/job_spawn.md), which receives a closure and starts its execution in a background thread, returning
+an unique integer id for such job:
 
-The module borrows the power of [pueue](https://github.com/Nukesor/pueue), it is possible to schedule background tasks to pueue, and manage those tasks (such as viewing logs, killing tasks, or getting the running status of all tasks, creating groups, pausing tasks etc etc)
+```nu
+'i am' | save status.txt
 
-Unlike terminal multiplexer, you don't need to attach to multiple tmux sessions, and get task status easily.
+job spawn { sleep 10sec; ' inevitable' | save --append status.txt }
+## => 1
 
-Here we provide a [nushell module](https://github.com/nushell/nu_scripts/tree/main/modules/background_task) that makes working with pueue easier.
+open status.txt
+## => i am
 
-Here is a setup example to make Nushell "support" background tasks:
+# wait for 10 seconds
+sleep 10sec
 
-1. Install pueue
-2. run `pueued`, you can refer to [start-the-daemon page](https://github.com/Nukesor/pueue/wiki/Get-started#start-the-daemon) for more information.
-3. Put the [task.nu](https://github.com/nushell/nu_scripts/blob/main/modules/background_task/task.nu) file under `$env.NU_LIB_DIRS`.
-4. Add a line to the `$nu.config-path` file: `use task.nu`
-5. Restart Nushell.
+open status.txt
+## => i am inevitable
path: book/background_task.md
user: login: 132ikl
body: ```suggestion
# => i am inevitable
```
created_at: 2025-03-20T02:34:25Z
author_association: MEMBER
diff_hunk: @@ -1,34 +1,77 @@
-# Background Tasks with Nu
+# Background Jobs
 
-Currently, Nushell doesn't have built-in background task management feature, but you can make it "support" background task with some tools, here are some examples:
+## Spawning Jobs
 
-1. Using a third-party task management tools, like [pueue](https://github.com/Nukesor/pueue)
-2. Using a terminal multiplexer, like [tmux](https://github.com/tmux/tmux/wiki) or [zellij](https://zellij.dev/)
+Nushell currently presents experimental support for thread-based background jobs.
 
-## Using Nu With Pueue
+Jobs can be can be spawned using [`job spawn`](/commands/docs/job_spawn.md), which receives a closure and starts its execution in a background thread, returning
+an unique integer id for such job:
 
-The module borrows the power of [pueue](https://github.com/Nukesor/pueue), it is possible to schedule background tasks to pueue, and manage those tasks (such as viewing logs, killing tasks, or getting the running status of all tasks, creating groups, pausing tasks etc etc)
+```nu
+'i am' | save status.txt
 
-Unlike terminal multiplexer, you don't need to attach to multiple tmux sessions, and get task status easily.
+job spawn { sleep 10sec; ' inevitable' | save --append status.txt }
+## => 1
 
-Here we provide a [nushell module](https://github.com/nushell/nu_scripts/tree/main/modules/background_task) that makes working with pueue easier.
+open status.txt
+## => i am
 
-Here is a setup example to make Nushell "support" background tasks:
+# wait for 10 seconds
+sleep 10sec
 
-1. Install pueue
-2. run `pueued`, you can refer to [start-the-daemon page](https://github.com/Nukesor/pueue/wiki/Get-started#start-the-daemon) for more information.
-3. Put the [task.nu](https://github.com/nushell/nu_scripts/blob/main/modules/background_task/task.nu) file under `$env.NU_LIB_DIRS`.
-4. Add a line to the `$nu.config-path` file: `use task.nu`
-5. Restart Nushell.
+open status.txt
+## => i am inevitable
+```
 
-Then you will get some commands to schedule background tasks. (e.g: `task spawn`, `task status`, `task log`)
+::: tip Note
+Unlike many other shells, Nushell jobs are **not** separate processes, and are instead implemented
+as background threads. An important side effect of that, is that all background jobs terminate once the shell process exits.
+:::
 
-Cons: It spawns a new Nushell interpreter to execute every single task, so it doesn't inherit current scope's variables, custom commands, alias definition.
-It only inherits environment variables whose value can be converted to a string.
-Therefore, if you want to use custom commands or variables, you have to [`use`](/commands/docs/use.md) or [`def`](/commands/docs/def.md) them within the given block.
+## Listing and Killing jobs
 
-## Using Nu With Terminal Multiplexer
+Active jobs can be queried with the [`job list`](/commands/docs/job_list.md) command, which returns a table with the information of the jobs which are currently executing.
+Jobs can also be kiled/interrupted by using the [`job kill`](/commands/docs/job_kill.md) command, which interrupts the job's thread and kills all of the job's child processes:
 
-You can choose and install a terminal multiplexer and use it.
+```nu
+let id = job spawn { sleep 1day }
 
-It allows you to easily switch between multiple programs in one terminal, detach them (they continue to run in the background) and reconnect them to a different terminal.  As a result, it is very flexible and usable.
+job list
+# => ┏━━━┳━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━┓
+# => ┃ # ┃ id ┃  type  ┃      pids      ┃
+# => ┣━━━╋━━━━╋━━━━━━━━╋━━━━━━━━━━━━━━━━┫
+# => ┃ 0 ┃  1 ┃ thread ┃ [list 0 items] ┃
+# => ┗━━━┻━━━━┻━━━━━━━━┻━━━━━━━━━━━━━━━━┛
+
+job kill $id
+
+job list
+# => ╭────────────╮
+# => │ empty list │
+# => ╰────────────╯
+```
+
+## Unix Ctrl-Z
+
+In unix targets (namely Linux and MacOS), Nushell's background job support also integrates with the Ctrl-Z feature
+of terminals (more specifically, the `SIGTSTP` signal), which allows users to suspend foreground processes into background jobs.
+When a running process is suspended, it is turned into a background job of type `frozen`. A frozen job can be reanimated into foreground with the
+[`job unfreeze`](/commands/docs/job_unfreeze.md) command.
+
+```
+long_running_process
+# (Ctrl-Z is pressed)
+
+job list
+# => ┏━━━┳━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━┓
+# => ┃ # ┃ id ┃  type  ┃      pids      ┃
+# => ┣━━━╋━━━━╋━━━━━━━━╋━━━━━━━━━━━━━━━━┫
+# => ┃ 0 ┃  1 ┃ frozen ┃ [list 1 items] ┃
+# => ┗━━━┻━━━━┻━━━━━━━━┻━━━━━━━━━━━━━━━━┛
+
+job unfreeze 1
+# (process is brought back where it stopped)
+```
+
+If no job id is provided to `job unfreeze`, it will unfreeze the job id of the most recently frozen job.
+Therefore, one can use `alias fg = job unfreeze` to achieve a behavior similar to the one of existing unix shells.
path: book/background_task.md
user: login: cosineblast
body: that looks good to me! (and I'm not even the reviewer)

created_at: 2025-03-29T19:51:37Z
author_association: CONTRIBUTOR

PR comments:
user: login: fdncred
created_at: 2025-03-03T20:01:34Z
body: > Quick question: How do I generate the .md files for new commands such as job spawn?

You don't need to do that. @hustcer generates all the commands shortly after each release.
author_association: CONTRIBUTOR
user: login: 132ikl
created_at: 2025-03-04T03:12:35Z
body: i'll take a look when i get the chance
author_association: MEMBER
user: login: 132ikl
created_at: 2025-03-30T21:29:13Z
body: looks great, thanks!
author_association: MEMBER
user: login: cosineblast
created_at: 2025-04-05T02:30:39Z
body: i think this may have broken the link to the background tasks section sidebar

![image](https://github.com/user-attachments/assets/18b52069-34f3-417a-b8ff-5b961948d37c)

any ideas on how to solve this?
author_association: CONTRIBUTOR
user: login: sholderbach
created_at: 2025-04-07T09:57:07Z
body: The sidebar config is under `.vuepress/configs/sidebar` which is sadly hidden from ripgrep by default. There the entries are named. (Due to the renaming the existing entry failed)
author_association: MEMBER
user: login: cosineblast
created_at: 2025-04-07T22:34:12Z
body: >  which is sadly hidden from ripgrep by default
Oh, that explains a lot, thx
author_association: CONTRIBUTOR