Devbox Global -- Documentation (#682)

Lagoja · web-flow · commit c826bec59e0f · 2023-02-24T13:30:25.000-08:00
## Summary

Adds a guide + CLI instructions for Devbox Global
Reconfigures the sidebar to make it easier to add

## How was it tested?

Localhost

---------

Signed-off-by: John Lago &lt;750845+Lagoja@users.noreply.github.com&gt;
diff --git a/docs/app/docs/cli_reference/devbox.md b/docs/app/docs/cli_reference/devbox.md
@@ -1,4 +1,4 @@
-# devbox CLI
+# devbox 
 
 Instant, easy, predictable shells and containers
 
@@ -18,6 +18,7 @@ devbox [flags]
 * [devbox add](./devbox_add.md)	 - Add a new package to your devbox
 * [devbox cloud](./devbox_cloud.md) - [Preview] Create and manage a remote dev environment with Devbox Cloud
 * [devbox generate](devbox_generate.md)  - Generate supporting files for your project
+* [devbox global](./devbox_global.md)	 - Manages global Devbox packages
 * [devbox info](devbox_info.md)  - Display package and plugin info
 * [devbox init](./devbox_init.md)	 - Initialize a directory as a devbox project
 * [devbox rm](./devbox_rm.md)	 - Remove a package from your devbox
diff --git a/docs/app/docs/cli_reference/devbox_cloud.md b/docs/app/docs/cli_reference/devbox_cloud.md
@@ -17,8 +17,12 @@ devbox cloud [subcommand] [flags]
   -q, --quiet   Quiet mode: Suppresses logs.
 ```
 
-## SEE ALSO
+## Subcommands
 
-* [devbox](devbox.md)	 - Instant, easy, predictable development environments
 * [devbox cloud forward](devbox_cloud_forward.md)	 - [Preview] Port forwards a local port to a remote devbox cloud port
 * [devbox cloud shell](devbox_cloud_shell.md)	 - [Preview] Shell into a cloud environment that matches your local devbox environment
+
+## SEE ALSO
+
+* [devbox](devbox.md)	 - Instant, easy, predictable development environments
+
diff --git a/docs/app/docs/cli_reference/devbox_generate.md b/docs/app/docs/cli_reference/devbox_generate.md
@@ -14,10 +14,13 @@ devbox generate <devcontainer|dockerfile> [flags]
   -q, --quiet   Quiet mode: Suppresses logs.
 ```
 
-## SEE ALSO
+## Subcommands
 
-* [devbox](devbox.md)	 - Instant, easy, predictable development environments
 * [devbox generate devcontainer](devbox_generate_devcontainer.md)	 - Generate Dockerfile and devcontainer.json files under .devcontainer/ directory
 * [devbox generate dockerfile](devbox_generate_dockerfile.md)	 - Generate a Dockerfile that replicates devbox shell
 * [devbox generate direnv](devbox_generate_direnv.md)  - Generate a .envrc file to use with direnv
 
+## SEE ALSO
+
+* [devbox](devbox.md)	 - Instant, easy, predictable development environments
+
diff --git a/docs/app/docs/cli_reference/devbox_global.md b/docs/app/docs/cli_reference/devbox_global.md
@@ -0,0 +1,34 @@
+# devbox global
+
+Top level command for managing global packages.
+
+You can use `devbox global` to install packages that you want to use across all your local devbox projects. For example -- if you usually use `ripgrep` for searching in all your projects, you can use `devbox add ripgrep` to make it available whenever you start a `devbox shell` without adding it to each project's `devbox.json.` 
+
+You can also use Devbox as a global package manager by adding the following line to your shellrc: 
+
+`exec "$(devbox global shellenv)"`
+
+For more details, see [Use Devbox as your Primary Package Manager](../devbox_global.md).
+
+```bash
+devbox global <subcommand> [flags]
+```
+
+## Options
+
+```bash
+  -c, --config string   path to directory containing a devbox.json config file
+  -h, --help            help for generate
+  -q, --quiet   Quiet mode: Suppresses logs.
+```
+
+## Subcommands
+* [devbox global add](devbox_global_add.md)	 - Add a global package to your devbox
+* [devbox global list](devbox_global_list.md)	 - List global packages
+* [devbox global pull](devbox_global_pull.md)	 - Pulls a global config from a file or URL.
+* [devbox global rm](devbox_global_rm.md)	 - Remove a global package 
+* [devbox global shellenv](devbox_global_shellenv.md)	 - Print shell commands that add global Devbox packages to your PATH
+
+## SEE ALSO
+
+* [devbox](devbox.md)	 - Instant, easy, predictable development environments
diff --git a/docs/app/docs/cli_reference/devbox_global_add.md b/docs/app/docs/cli_reference/devbox_global_add.md
@@ -0,0 +1,18 @@
+# devbox global add
+
+Add a new global package.
+
+```bash
+devbox global add <pkg>... [flags]
+```
+
+## Options
+
+```bash
+  -h, --help   help for add
+  -q, --quiet  suppresses logs
+```
+
+## SEE ALSO
+
+* [devbox global](devbox_global.md)	 - Manages global Devbox packages
diff --git a/docs/app/docs/cli_reference/devbox_global_list.md b/docs/app/docs/cli_reference/devbox_global_list.md
@@ -0,0 +1,21 @@
+# devbox global list
+
+Lists all the packages you have installed globally
+
+```bash
+devbox global list <pkg>... [flags]
+```
+## Aliases
+
+list, ls
+
+## Options
+
+```bash
+  -h, --help   help for list
+  -q, --quiet  suppresses logs
+```
+
+## SEE ALSO
+
+* [devbox global](devbox_global.md)	 - Manages global Devbox packages
diff --git a/docs/app/docs/cli_reference/devbox_global_pull.md b/docs/app/docs/cli_reference/devbox_global_pull.md
@@ -0,0 +1,18 @@
+# devbox global pull
+
+Pulls a global config from a file or URL. URLs must be prefixed with 'http://' or 'https://'.
+
+```bash
+devbox global pull <file> | <url> [flags]
+```
+
+## Options
+
+```bash
+  -h, --help   help for pull
+  -q, --quiet  suppresses logs
+```
+
+## SEE ALSO
+
+* [devbox global](devbox_global.md)	 - Manages global Devbox packages
diff --git a/docs/app/docs/cli_reference/devbox_global_rm.md b/docs/app/docs/cli_reference/devbox_global_rm.md
@@ -0,0 +1,18 @@
+# devbox global rm
+
+Removes a package from your global config
+
+```bash
+devbox global rm <pkg> [flags]
+```
+
+## Options
+
+```bash
+  -h, --help   help for rm
+  -q, --quiet  suppresses logs
+```
+
+## SEE ALSO
+
+* [devbox global](devbox_global.md)	 - Manages global Devbox packages
diff --git a/docs/app/docs/cli_reference/devbox_global_shellenv.md b/docs/app/docs/cli_reference/devbox_global_shellenv.md
@@ -0,0 +1,26 @@
+# devbox global shellenv
+
+Print shell commands that add global Devbox packages to your PATH
+
+- To add the global packages to the PATH of your current shell, run the following command: 
+    
+    ```bash
+    . <(devbox global shellenv)
+    ```
+    
+- To add the global packages to the PATH of all new shells, add the following line to your shell's config file (e.g. `~/.bashrc` or `~/.zshrc`):
+    
+    ```bash
+    eval "$(devbox global shellenv)"
+    ```
+
+## Options
+
+```bash
+  -h, --help   help for shellenv
+  -q, --quiet  suppresses logs
+```
+
+## SEE ALSO
+
+* [devbox global](devbox_global.md)	 - Manages global Devbox packages
diff --git a/docs/app/docs/cli_reference/devbox_services.md b/docs/app/docs/cli_reference/devbox_services.md
@@ -14,11 +14,13 @@ devbox services <ls|restart|start|stop> [flags]
   -q, --quiet   Quiet mode: Suppresses logs.
 ```
 
-## SEE ALSO
+## Subcommands
 
-* [devbox](devbox.md)	 - Instant, easy, predictable development environments
 * [devbox services ls](devbox_services_ls.md)	 - List available services
 * [devbox services restart](devbox_services_restart.md)	 - Restarts service. If no service is specified, restarts all services
 * [devbox services start](devbox_services_start.md)	 - Starts service. If no service is specified, starts all services
 * [devbox services stop](devbox_services_stop.md)	 - Stops service. If no service is specified, stops all services
 
+## SEE ALSO
+
+* [devbox](devbox.md)	 - Instant, easy, predictable development environments
diff --git a/docs/app/docs/contributor-quickstart.md b/docs/app/docs/contributor-quickstart.md
@@ -67,6 +67,7 @@ Devbox requires the [Nix Package Manager](https://nixos.org/download.html). If N
 ## Next Steps
 
 ### Learn more about Devbox
+* **[Devbox Global](devbox_global.md):** Learn how to use the devbox as a global package manager
 * **[Devbox Scripts](guides/scripts.md):** Automate setup steps and configuration for your shell using Devbox Scripts.
 * **[Configuration Guide](configuration.md):** Learn how to configure your shell and dev environment with `devbox.json`.
 * **[Browse Examples](https://github.com/jetpack-io/devbox-examples):** You can see how to create a development environment for your favorite tools or languages by browsing the Devbox Examples repo.
diff --git a/docs/app/docs/devbox_cloud/beta_faq.md b/docs/app/docs/devbox_cloud/beta_faq.md
@@ -1,5 +1,6 @@
 ---
 title: Devbox Cloud Open Beta FAQ
+sidebar_position: 4
 ---
 
 ### What do I need to use Devbox Cloud?
diff --git a/docs/app/docs/devbox_cloud/browser_getting_started.md b/docs/app/docs/devbox_cloud/browser_getting_started.md
@@ -1,5 +1,6 @@
 ---
 title: Getting Started From Your Browser
+sidebar_position: 3
 ---
 
 In addition to using [Devbox Cloud from your terminal](getting_started.md), you can use Devbox Cloud to preview Github projects directly in your browser. The Devbox Cloud Shell comes with the Devbox CLI preinstalled, so you can easily install your projects dependencies or run projects that include a `devbox.json`
diff --git a/docs/app/docs/devbox_cloud/getting_started.md b/docs/app/docs/devbox_cloud/getting_started.md
@@ -1,4 +1,7 @@
-# Getting Started from your Terminal
+---
+title: Getting Started From Your Terminal
+sidebar_position: 2
+---
 
 Devbox Cloud is a new way to create and run your Devbox Project in an isolated cloud environment. 
 
diff --git a/docs/app/docs/devbox_cloud/index.mdx b/docs/app/docs/devbox_cloud/index.mdx
@@ -1,5 +1,6 @@
 ---
 title: Devbox Cloud Open Beta
+sidebar_position: 1
 ---
 import Tabs from '@theme/Tabs'
 import TabItem from '@theme/TabItem';
diff --git a/docs/app/docs/devbox_global.md b/docs/app/docs/devbox_global.md
@@ -0,0 +1,130 @@
+---
+title: Use Devbox as your Primary Package manager
+---
+
+In addition to managing isolated development environments, you can use Devbox as a general package manager. Devbox Global allows you to add packages to a global `devbox.json.` This is useful for installing a standard set of tools you want to use across multiple Devbox Projects.
+
+For example — if you use ripgrep as your preferred search tool, you can add it to your global Devbox profile with `devbox global add ripgrep`. Now whenever you start a Devbox shell, you will have ripgrep available, even if it's not in the project's devbox.json. 
+
+<figure>
+
+![Installing ripgrep using `devbox global add ripgrep](../../app/static/img/devbox_global.svg)
+
+<figcaption>Installing Packages with Devbox Global</figcaption>
+</figure>
+
+You can also use `devbox global` to replace package managers like `brew` and `apt` by adding the global profile to your path. Because Devbox uses Nix to install packages, you can sync your global config to install the same packages on any machine. 
+
+Devbox saves your global config in a `devbox.json` file in your home directory. This file can be shared with other users or checked into source control to synchronize it across machines.
+
+## Adding and Managing Global Packages
+
+You can install a package using `devbox global add [<package>]`, where the package names should be a list of [Nix Packages](https://search.nixos.org/packages) you want to install. 
+
+For example, if we wanted to install ripgrep, vim, and git to our global profile, we could run:
+
+```bash
+devbox global add ripgrep vim git
+
+# Output:
+ripgrep is now installed
+vim is now installed
+git is now installed
+```
+
+Once installed, the packages will be available whenever you start a Devbox Shell, even if it's not included in the project's `devbox.json`. 
+
+To view a full list of global packages, you can run `devbox global list`: 
+
+```bash
+devbox global list
+
+# Output:
+* ripgrep
+* vim
+* git
+```
+
+To remove a global package, use: 
+
+```bash
+devbox global remove ripgrep
+
+# Output: 
+ripgrep was removed
+```
+
+## Using Global Packages in your Host Shell
+
+If you want to make your global packages available in your host shell, you can add them to your shell PATH. Running `devbox global shellenv` will print the command necessary to source the packages. 
+
+
+### Add Global Packages to your current Host Shell
+To temporarily add the global packages to your current shell, run: 
+
+```bash
+. <(devbox global shellenv)
+```
+    
+You can also add a hook to your shell's config to make them available whenever you launch your shell:
+
+### Bash
+
+Add the following command to your `~/.bashrc` file:
+
+```bash
+eval "$(devbox global shellenv)"
+```
+
+Make sure to add this hook before any other hooks that use your global packages.
+
+### Zsh
+Add the following command to your `~/.zshrc` file:
+
+```bash
+eval "$(devbox global shellenv)"
+```
+
+### Fish
+
+Add the following command to your `~/.config/fish/config.fish` file:
+
+```bash
+devbox global shellenv | source
+```
+
+
+## Sharing Your Global Config
+
+Your global `devbox.json` will be stored in $XDG_DATA_HOME/devbox/global/devbox.json. If $XDG_DATA_HOME is not set, it will default to `~/.local/share/devbox/global/devbox.json`. 
+
+If you want to share your configuration with across machines or with other users, you can copy this file to a git repository or host it online.  You can then download and set the config as your global profile using `devbox global pull <path> | <url>`.
+
+```bash 
+# Load the global config from a file
+
+devbox global pull /path/to/devbox.json
+
+# Load the global config from a github repo
+
+devbox global pull https://raw.githubusercontent.com/org/repo/branch/path/to/devbox.json
+```
+
+## Next Steps
+
+### Learn more about Devbox
+
+* **[Getting Started](quickstart.mdx):** Learn how to install Devbox and create your first Devbox Shell.
+* **[Devbox Scripts](guides/scripts.md):** Automate setup steps and configuration for your shell using Devbox Scripts.
+* **[Configuration Guide](configuration.md):** Learn how to configure your shell and dev environment with `devbox.json`.
+* **[Browse Examples](https://github.com/jetpack-io/devbox-examples):** You can see how to create a development environment for your favorite tools or languages by browsing the Devbox Examples repo.
+
+### Use Devbox with your IDE
+
+* **[Direnv Integration](ide_configuration/direnv.md):** Devbox can integrate with [direnv](https://direnv.net/) to automatically activate your shell and packages when you navigate to your project.
+* **[Devbox for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=jetpack-io.devbox):** Install our VS Code extension to speed up common Devbox workflows or to use Devbox in a devcontainer.
+
+### Get Involved
+
+* **[Join our Discord Community](https://discord.gg/jetpack-io):** Chat with the development team and our growing community of Devbox users.
+* **[Visit us on Github](https://github.com/jetpack-io/devbox):** File issues and provide feedback, or even open a PR to contribute to Devbox or our Docs.
diff --git a/docs/app/docs/installing_devbox.md b/docs/app/docs/installing_devbox.md
@@ -11,4 +11,9 @@ Use the following install script to get the latest version of Devbox:
 curl -fsSL https://get.jetpack.io/devbox | bash
 ```
 
-Devbox requires the [Nix Package Manager](https://nixos.org/download.html). If Nix is not detected on your machine when running a command, Devbox will automatically install it for you with the default settings for your OS. Don't worry: You can use Devbox without needing to learn the Nix Language.
+Devbox requires the [Nix Package Manager](https://nixos.org/download.html). If Nix is not detected on your machine when running a command, Devbox will automatically install it for you with the default settings for your OS. Don't worry: You can use Devbox without needing to learn the Nix Language.
+
+## Next Steps
+
+* **[Getting Started](quickstart.mdx):** Learn how to create a dev environment with Devbox
+* **[Devbox Global](devbox_global.md):** Learn how to use the devbox as a global package manager
diff --git a/docs/app/docs/quickstart.mdx b/docs/app/docs/quickstart.mdx
@@ -143,6 +143,7 @@ Once you publish your Devbox project to Github, you can help other developers ge
 ## Next Steps
 
 ### Learn more about Devbox
+* **[Devbox Global](devbox_global.md):** Learn how to use the devbox as a global package manager
 * **[Devbox Scripts](guides/scripts.md):** Automate setup steps and configuration for your shell using Devbox Scripts.
 * **[Configuration Guide](configuration.md):** Learn how to configure your shell and dev environment with `devbox.json`.
 * **[Browse Examples](https://github.com/jetpack-io/devbox-examples):** You can see how to create a development environment for your favorite tools or languages by browsing the Devbox Examples repo.
diff --git a/docs/app/sidebars.js b/docs/app/sidebars.js
diff --git a/docs/app/static/img/devbox_global.svg b/docs/app/static/img/devbox_global.svg
