Add docs for --env and devbox run changes (#1366)

## Summary

Docs for new features in 0.5.11

## How was it tested?

Localhost `yarn start`

Author: Lagoja

docs/app/docs/cli_reference/devbox_generate_direnv.md

@@ -12,6 +12,8 @@ devbox generate direnv [flags]
 | Option | Description |
 | --- | --- |
 | `-c, --config string` | path to directory containing a devbox.json config file |
+|  `-e, --env stringToString` |  environment variables to set in the devbox environment (default []) |
+|  `--env-file string` | path to a file containing environment variables to set in the devbox environment. If the file does not exist, then this parameter is ignored |
 | `-h, --help` | help for generate |
 | `-q, --quiet` | Quiet mode: Suppresses logs. |
 

docs/app/docs/cli_reference/devbox_global_add.md

@@ -11,6 +11,7 @@ devbox global add <pkg>... [flags]
 <!-- Markdown Table of Options -->
 | Option | Description |
 | --- | --- |
+| `--allow-insecure` | Allow adding packages marked as insecure |
 | `-h, --help` | help for add |
 | `-q, --quiet` | suppresses logs |
 

docs/app/docs/cli_reference/devbox_global_run.md

@@ -29,6 +29,8 @@ Run a script (defined as `"moo": "cowsay moo"`) in your devbox.json:
 <!-- Markdown Table of Options -->
 | Option | Description |
 | --- | --- |
+|  `-e, --env stringToString` |  environment variables to set in the devbox environment (default []) |
+|  `--env-file string` | path to a file containing environment variables to set in the devbox environment |
 | `-h, --help` | help for global run |
 | `-q, --quiet` | suppresses logs |
 

docs/app/docs/cli_reference/devbox_global_services.md

@@ -11,6 +11,8 @@ devbox global services [command]
 <!-- Markdown Table of Options -->
 | Option | Description |
 | --- | --- |
+|  `-e, --env stringToString` |  environment variables to set in the devbox environment (default []) |
+|  `--env-file string` | path to a file containing environment variables to set in the devbox environment |
 | `-h, --help` | help for global services |
 | `-q, --quiet` | suppresses logs |
 

docs/app/docs/cli_reference/devbox_run.md

@@ -2,12 +2,12 @@
 
 Starts a new interactive shell and runs your target script in it. The shell will exit once your target script is completed or when it is terminated via CTRL-C. Scripts can be defined in your `devbox.json`.
 
-You can also run arbitrary commands in your devbox shell by passing them as arguments to `devbox run`. For example: 
+You can also run arbitrary commands in your devbox shell by passing them as arguments to `devbox run`. For example:
 
 ```bash
   devbox run echo "Hello World"
 ```
-Will print `Hello World` to the console from within your devbox shell. 
+Will print `Hello World` to the console from within your devbox shell.
 
 For more details, read our [scripts guide](../guides/scripts.md)
 
@@ -22,7 +22,11 @@ For more details, read our [scripts guide](../guides/scripts.md)
 # Run a command directly:
   devbox add cowsay
   devbox run cowsay hello
-  devbox run -- cowsay -d hello
+# Run a command that takes flags:
+  devbox run cowsay -d hello
+# Pass flags to devbox while running a command.
+# All `devbox run` flags must be passed before the command
+  devbox run -q cowsay -d hello
 
 #Run a script (defined as `"moo": "cowsay moo"`) in your devbox.json:
   devbox run moo
@@ -34,6 +38,8 @@ For more details, read our [scripts guide](../guides/scripts.md)
 | Option | Description |
 | --- | --- |
 | `-c, --config string` | path to directory containing a devbox.json config file |
+| `-e, --env stringToString` |  environment variables to set in the devbox environment (default []) |
+| `--env-file string` | path to a file containing environment variables to set in the devbox environment |
 | `-h, --help` | help for run |
 | `-q, --quiet` | Quiet mode: Suppresses logs. |
 

docs/app/docs/cli_reference/devbox_services_restart.md

@@ -15,6 +15,8 @@ devbox services restart [service]... [flags]
 <!-- Markdown Table of Options -->
 | Option | Description |
 | --- | --- |
+|  `-e, --env stringToString` |  environment variables to set in the devbox environment (default []) |
+|  `--env-file string` | path to a file containing environment variables to set in the devbox environment |
 | `-h, --help` | help for restart |
 | `-q, --quiet` | Quiet mode: Suppresses logs. |
 

docs/app/docs/cli_reference/devbox_services_start.md

@@ -15,6 +15,8 @@ devbox services start [service]... [flags]
 <!-- Markdown Table of Options -->
 | Option | Description |
 | --- | --- |
+|  `-e, --env stringToString` |  environment variables to set in the devbox environment (default []) |
+|  `--env-file string` | path to a file containing environment variables to set in the devbox environment |
 | `-h, --help` | help for start |
 | `-q, --quiet` | Quiet mode: Suppresses logs. |
 

docs/app/docs/cli_reference/devbox_services_stop.md

@@ -11,6 +11,8 @@ devbox services stop [service]... [flags]
 <!-- Markdown Table of Options -->
 | Option | Description |
 | --- | --- |
+|  `-e, --env stringToString` |  environment variables to set in the devbox environment (default []) |
+|  `--env-file string` | path to a file containing environment variables to set in the devbox environment |
 | `-h, --help` | help for stop |
 | `-q, --quiet` | Quiet mode: Suppresses logs. |
 

docs/app/docs/cli_reference/devbox_services_up.md

@@ -28,6 +28,8 @@ devbox services up web
 | --- | --- |
 | `-b, --background` | Run service in background |
 | `-c, --config string` | path to directory containing a devbox.json config file |
+|  `-e, --env stringToString` |  environment variables to set in the devbox environment (default []) |
+|  `--env-file string` | path to a file containing environment variables to set in the devbox environment |
 | `-h, --help` | help for up |
 | `--process-compose-file string` | path to process compose file or directory  containing process compose-file.yaml|yml. Default is directory containing devbox.json |
 | `-q, --quiet` | Quiet mode: Suppresses logs. |

docs/app/docs/cli_reference/devbox_shell.md

@@ -4,7 +4,7 @@ Start a new shell or run a command with access to your packages
 
 ## Synopsis
 
-Start a new shell or run a command with access to your packages. The interactive shell will use the devbox.json in your current directory, or the directory provided with `dir`. 
+Start a new shell or run a command with access to your packages. The interactive shell will use the devbox.json in your current directory, or the directory provided with `dir`.
 
 ```bash
 devbox shell [<dir>] [flags]
@@ -15,6 +15,8 @@ devbox shell [<dir>] [flags]
 <!-- Markdown Table of Options -->
 | Option | Description |
 | --- | --- |
+|  `-e, --env stringToString` |  environment variables to set in the devbox environment (default []) |
+|  `--env-file string` | path to a file containing environment variables to set in the devbox environment |
 | `--print-env` | Print a script to setup a devbox shell environment |
 | `-h, --help` | help for shell |
 | `-q, --quiet` | Quiet mode: Suppresses logs. |

docs/app/docs/cli_reference/devbox_shellenv.md

@@ -12,6 +12,8 @@ devbox shellenv [flags]
 | Option | Description |
 | --- | --- |
 | `-c, --config string` | path to directory containing a devbox.json config file |
+|  `-e, --env stringToString` |  environment variables to set in the devbox environment (default []) |
+|  `--env-file string` | path to a file containing environment variables to set in the devbox environment |
 | `-h, --help` | help for shellenv |
 | `-q, --quiet` | suppresses logs |
 

docs/app/docs/configuration.md

@@ -147,15 +147,15 @@ To run multiple commands in a single script, you can pass them as an array:
 }
 ```
 
-### Includes
+### Include
 
 Includes can be used to explicitly add extra configuration or plugins to your Devbox project. Currently this only supports adding our [built-in plugins](guides/plugins.md) to your project.
 
-You should use this section to activate plugins when you install a package from a [Flake](guides/using_flakes.md) that uses a plugin. To ensure that a plugin is activated for your project, add it to the `includes` section of your `devbox.json`. For example, to explicitly activate the PHP plugin, you can add the following to your `devbox.json`:
+You should use this section to activate plugins when you install a package from a [Flake](guides/using_flakes.md) that uses a plugin. To ensure that a plugin is activated for your project, add it to the `include` section of your `devbox.json`. For example, to explicitly activate the PHP plugin, you can add the following to your `devbox.json`:
 
 ```json
 {
-    "includes": [
+    "include": [
         "plugin:php-config"
     ]
 }

docs/app/docs/guides/scripts.md

@@ -2,19 +2,19 @@
 title: Running Scripts
 ---
 
-This doc describes how to configure and run scripts using `devbox run`. Scripts started with `devbox run` are launched in a interactive `devbox shell` that terminates once the script finishes, or is interrupted by CTRL-C. 
+This doc describes how to configure and run scripts using `devbox run`. Scripts started with `devbox run` are launched in a interactive `devbox shell` that terminates once the script finishes, or is interrupted by CTRL-C.
 
-Scripts will run after your packages finish installing, and after your `init_hook` completes. 
+Scripts will run after your packages finish installing, and after your `init_hook` completes.
 
 ## Configuring scripts
 
-Scripts can be added in your `devbox.json`. Scripts require a unique name, and a command or list of commands to run: 
+Scripts can be added in your `devbox.json`. Scripts require a unique name, and a command or list of commands to run:
 
 ```json
 "shell": {
     "init_hook": "echo \"Hello \"",
     "scripts": {
-        "echo_once": "echo \"World\"", 
+        "echo_once": "echo \"World\"",
         "echo_twice": [
             "echo \"World\"",
             "echo \"Again\""
@@ -25,7 +25,7 @@ Scripts can be added in your `devbox.json`. Scripts require a unique name, and a
 
 ## Running your scripts
 
-To run a script, use `devbox run <script_name>`. This will start your shell, run your `init_hook`, and then run the script: 
+To run a script, use `devbox run <script_name>`. This will start your shell, run your `init_hook`, and then run the script:
 
 ```bash
 $ devbox run echo_once
@@ -52,17 +52,37 @@ You can use `devbox run` to run any command in your Devbox shell, even if you ha
 devbox run echo "Hello World"
 ```
 
-For commands that use flags, you can use the `--` separator to tell Devbox that the rest of the command is a single command to run. For example, the following command will show you all the processes listening on port 80:
+You can also run commands that use flags as normal. For example:
 
 ```bash
-devbox run -- lsof -i :80
+devbox run lsof -i :80
 ```
 
+Note that if you want to pass flags to `devbox run`, you should pass them before the command. For example:
+
+```bash
+# Run `lsof -i :80` in your devbox shell in quiet mode
+devbox run -q lsof -i :80
+```
+
+## Run Scripts with Custom Environment Variables
+
+You can use the `--env` flag to set custom environment variables in your Devbox shell. For example, the following command will set the `MY_VAR` environment variable to `my_value` when running the `echo` command:
+
+```bash
+devbox run --env MY_VAR=my_value echo $MY_VAR
+```
+
+You can also load environment variables from a .env file using the `--env-file` flag. For example, the following command will load the environment variables from the `.env.devbox` file in your current directory:
+
+```bash
+devbox run --env-file .env.devbox echo $MY_VAR
+```
 
 ## Tips on using Scripts
 
 1. Since `init_hook` runs everytime you start your shell, you should use primarily use it for setting environment variables and aliases. For longer running tasks like database setup, you can create and run a Devbox script
-2. You can use Devbox scripts to start and manage long running background processes and daemons. 
+2. You can use Devbox scripts to start and manage long running background processes and daemons.
    1. For example -- If you are working on a LAMP stack project, you can use scripts to start MySQL and Apache in separate shells and monitor their logs. Once you are done developing, you can use CTRL-C to exit the processes and shells
 3. If a script feels too long to put it directly in `devbox.json`, you can save it as a shell script in your project, and then invoke it in your `devbox scripts`.
-4. For more ideas, see the LAMP stack example in our [Devbox examples repo](https://github.com/jetpack-io/devbox/tree/main/examples/stacks/lapp-stack). 
+4. For more ideas, see the LAMP stack example in our [Devbox examples repo](https://github.com/jetpack-io/devbox/tree/main/examples/stacks/lapp-stack).

docs/app/docs/ide_configuration/direnv.md

@@ -1,20 +1,20 @@
 ---
-title: direnv 
+title: direnv
 ---
 
 
 ## direnv
 ___
 [direnv](https://direnv.net) is an open source environment management tool that allows setting unique environment variables per directory in your file system. This guide covers how to configure direnv to seamlessly work with a devbox project.
 
-:::note 
+:::note
 Devbox 0.5.0 makes changes to how the environment is sourced in order to ensure better compatibility with the user's host shell. This may raise some errors if you generated your `.envrc` file with an older version of devbox.
-    
+
 If you see any errors when activating your `.envrc` file, you will need to run `devbox generate direnv --force`, and then re-run `devbox shell` to apply the latest changes. Be sure to back up your old `.envrc` file before running this command.
 :::
 
 ### Prerequisites
-* Install direnv and hook it to your shell. Follow [this guide](https://direnv.net/#basic-installation) if you haven't done it. 
+* Install direnv and hook it to your shell. Follow [this guide](https://direnv.net/#basic-installation) if you haven't done it.
 
 ### Setting up Devbox Shell and direnv
 
@@ -45,6 +45,48 @@ direnv: loading ~/src/devbox/docs/.envrc
 direnv: using devbox
 ```
 
+#### Adding Custom Env Variables or Env Files to your Direnv Config
+
+In some cases, you may want to override certain environment variables in your Devbox config when running it locally. You can add custom environment variables from the command line or from a file using the `--env` and `--env-file` flags.
+
+If you would like to add custom environment variables to your direnv config, you can do so by passing the `--env` flag to `devbox generate direnv`. This flag takes a comma-separated list of key-value pairs, where the key is the name of the environment variable and the value is the value of the environment variable. For example, if you wanted to add a `MY_CUSTOM_ENV_VAR` environment variable with a value of `my-custom-value`, you would run the following command:
+
+```bash
+devbox generate direnv --env MY_CUSTOM_ENV_VAR=my-value
+```
+
+The resulting .envrc will have the following:
+
+```bash
+# Automatically sets up your devbox environment whenever you cd into this
+# directory via our direnv integration:
+
+eval "$(devbox generate direnv --print-envrc --env MY_CUSTOM_ENV_VAR=my-value)"
+
+# check out https://www.jetpack.io/devbox/docs/ide_configuration/direnv/
+# for more details
+```
+
+You can also tell direnv to read environment variables from a custom `.env` file by passing the `--env-file` flag to `devbox generate direnv`. This flag takes a path to a file containing environment variables to set in the devbox environment. If the file does not exist, then this parameter is ignored. For example, if you wanted to add a `.env.devbox` file located in your project root, you would run the following command:
+
+```bash
+devbox generate direnv --env-file .env.devbox
+```
+
+The resulting .envrc will have the following:
+
+```bash
+# Automatically sets up your devbox environment whenever you cd into this
+# directory via our direnv integration:
+
+eval "$(devbox generate direnv --print-envrc --env-file .env.devbox)"
+
+# check out https://www.jetpack.io/devbox/docs/ide_configuration/direnv/
+# for more details
+```
+
+Note that if Devbox cannot find the env file provided to the flag, it will ignore the flag and load your Devbox shell environment as normal
+
 ### Global settings for direnv
 
 Note that every time changes are made to `devbox.json` via `devbox add ...`, `devbox rm ...` or directly editing the file, requires `direnv allow` to run so that `direnv` can setup the new changes.