> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/opencode-ai/opencode/llms.txt
> Use this file to discover all available pages before exploring further.

# Shell configuration

> Configure the shell used by OpenCode's bash tool

OpenCode executes shell commands through its bash tool. You can customize which shell is used and how it's configured.

## Default behavior

By default, OpenCode uses the shell specified in your `SHELL` environment variable. If `SHELL` is not set, it falls back to `/bin/bash`.

```bash theme={null}
# OpenCode will use your default shell
echo $SHELL
# /bin/zsh (or /bin/bash, etc.)
```

## Configuration options

### Setting the shell path

You can override the default shell in your OpenCode configuration:

```json .opencode.json theme={null}
{
  "shell": {
    "path": "/bin/zsh"
  }
}
```

### Passing shell arguments

Shell arguments allow you to control how the shell is initialized:

```json .opencode.json theme={null}
{
  "shell": {
    "path": "/bin/zsh",
    "args": ["-l"]
  }
}
```

<Info>
  The default argument is `["-l"]`, which starts the shell as a login shell, loading your profile files.
</Info>

## Common configurations

### Bash

<Tabs>
  <Tab title="Login shell (default)">
    Loads `.bash_profile` and `.bashrc`:

    ```json .opencode.json theme={null}
    {
      "shell": {
        "path": "/bin/bash",
        "args": ["-l"]
      }
    }
    ```
  </Tab>

  <Tab title="Interactive shell">
    Loads `.bashrc` only:

    ```json .opencode.json theme={null}
    {
      "shell": {
        "path": "/bin/bash",
        "args": ["-i"]
      }
    }
    ```
  </Tab>

  <Tab title="Non-interactive">
    No profile loading:

    ```json .opencode.json theme={null}
    {
      "shell": {
        "path": "/bin/bash",
        "args": []
      }
    }
    ```
  </Tab>
</Tabs>

### Zsh

<Tabs>
  <Tab title="Login shell (recommended)">
    Loads `.zprofile` and `.zshrc`:

    ```json .opencode.json theme={null}
    {
      "shell": {
        "path": "/bin/zsh",
        "args": ["-l"]
      }
    }
    ```
  </Tab>

  <Tab title="Interactive shell">
    Loads `.zshrc` only:

    ```json .opencode.json theme={null}
    {
      "shell": {
        "path": "/bin/zsh",
        "args": ["-i"]
      }
    }
    ```
  </Tab>
</Tabs>

### Fish

```json .opencode.json theme={null}
{
  "shell": {
    "path": "/usr/bin/fish",
    "args": ["-l"]
  }
}
```

### Custom shell

You can use any shell that supports the `-c` option for command execution:

```json .opencode.json theme={null}
{
  "shell": {
    "path": "/usr/local/bin/custom-shell",
    "args": ["--custom-arg"]
  }
}
```

## Shell argument reference

<AccordionGroup>
  <Accordion title="-l (login shell)">
    Starts the shell as a login shell, loading profile files.

    **Bash:** Loads `/etc/profile`, `~/.bash_profile`, `~/.bash_login`, and `~/.profile`

    **Zsh:** Loads `/etc/zprofile`, `~/.zprofile`, `/etc/zshrc`, and `~/.zshrc`

    **Use when:** You need your full shell environment, including PATH modifications, aliases, and environment variables.
  </Accordion>

  <Accordion title="-i (interactive shell)">
    Starts the shell in interactive mode.

    **Bash:** Loads `~/.bashrc`

    **Zsh:** Loads `~/.zshrc`

    **Use when:** You want interactive features but don't need full profile loading.
  </Accordion>

  <Accordion title="No arguments">
    Starts a non-interactive, non-login shell.

    **Use when:** You want minimal overhead and don't need your custom environment.
  </Accordion>

  <Accordion title="-c <command>">
    Executes a specific command (automatically used by OpenCode).

    <Warning>
      Don't include `-c` in your `args` configuration. OpenCode automatically adds it when executing commands.
    </Warning>
  </Accordion>
</AccordionGroup>

## Use cases

### Loading custom environment variables

If your development environment requires specific environment variables, use a login shell:

```json .opencode.json theme={null}
{
  "shell": {
    "path": "/bin/bash",
    "args": ["-l"]
  }
}
```

Then in your `~/.bash_profile` or `~/.zprofile`:

```bash ~/.bash_profile theme={null}
export NODE_PATH="/usr/local/lib/node_modules"
export GOPATH="$HOME/go"
export PATH="$PATH:$GOPATH/bin"
```

### Using version managers

If you use version managers like `nvm`, `rbenv`, or `pyenv`, you typically need a login shell:

```json .opencode.json theme={null}
{
  "shell": {
    "path": "/bin/zsh",
    "args": ["-l"]
  }
}
```

```bash ~/.zprofile theme={null}
# Load nvm
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

# Load rbenv
export PATH="$HOME/.rbenv/bin:$PATH"
eval "$(rbenv init -)"
```

### Minimal overhead

For faster command execution without environment customization:

```json .opencode.json theme={null}
{
  "shell": {
    "path": "/bin/bash",
    "args": []
  }
}
```

### CI/CD environments

In containerized or CI environments, you might want to ensure consistent behavior:

```json .opencode.json theme={null}
{
  "shell": {
    "path": "/bin/sh",
    "args": []
  }
}
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Commands not found">
    **Symptoms:** Tools like `npm`, `python`, or custom scripts are not found

    **Solution:** Use a login shell to load your PATH:

    ```json .opencode.json theme={null}
    {
      "shell": {
        "path": "/bin/bash",
        "args": ["-l"]
      }
    }
    ```

    Verify your PATH is set correctly:

    ```bash ~/.bash_profile theme={null}
    export PATH="$HOME/.local/bin:$PATH"
    ```
  </Accordion>

  <Accordion title="Aliases not working">
    **Symptoms:** Shell aliases defined in your profile don't work

    **Cause:** Aliases are typically only available in interactive shells

    **Solution:** Use functions instead of aliases, or use an interactive shell:

    ```json .opencode.json theme={null}
    {
      "shell": {
        "path": "/bin/bash",
        "args": ["-i"]
      }
    }
    ```

    Better approach - convert aliases to functions:

    ```bash ~/.bashrc theme={null}
    # Instead of: alias gs="git status"
    # Use:
    gs() { git status "$@"; }
    ```
  </Accordion>

  <Accordion title="Slow command execution">
    **Symptoms:** Commands take a long time to start

    **Cause:** Your shell profile may be loading slowly (plugins, external tools, etc.)

    **Solution:** Profile your shell startup:

    ```bash theme={null}
    # For bash
    time bash -l -c 'echo loaded'

    # For zsh
    time zsh -l -c 'echo loaded'
    ```

    Optimize your profile files by:

    * Lazy-loading plugins and tools
    * Removing unnecessary initialization
    * Using a faster shell configuration
  </Accordion>

  <Accordion title="Environment variables not set">
    **Symptoms:** Environment variables you set in your profile aren't available

    **Solution:** Ensure you're using a login shell and the variables are exported:

    ```bash ~/.bash_profile theme={null}
    # Use export to make variables available to child processes
    export MY_VAR="value"
    ```
  </Accordion>

  <Accordion title="Permission denied errors">
    **Symptoms:** Shell can't execute commands or scripts

    **Solution:**

    * Verify the shell path is correct and executable:

    ```bash theme={null}
    ls -l /bin/bash
    # Should show: -rwxr-xr-x
    ```

    * Ensure scripts have execute permissions:

    ```bash theme={null}
    chmod +x /path/to/script.sh
    ```
  </Accordion>
</AccordionGroup>

## Advanced configuration

### Per-project shell configuration

You can use a local `.opencode.json` in your project directory to override the global shell configuration:

```json ./.opencode.json theme={null}
{
  "shell": {
    "path": "/bin/bash",
    "args": ["-l"]
  }
}
```

This is useful when different projects require different shell environments.

### Setting the SHELL environment variable

Alternatively, you can set the `SHELL` environment variable when launching OpenCode:

```bash theme={null}
SHELL=/bin/zsh opencode
```

### Testing your shell configuration

To test that your shell configuration works correctly:

<Steps>
  <Step title="Check shell path">
    Verify the shell executable exists:

    ```bash theme={null}
    which bash  # or zsh, fish, etc.
    ```
  </Step>

  <Step title="Test command execution">
    Test that commands run correctly:

    ```bash theme={null}
    /bin/bash -l -c 'echo $PATH'
    ```
  </Step>

  <Step title="Verify environment loading">
    Check that your environment is loaded:

    ```bash theme={null}
    /bin/bash -l -c 'env | grep MY_CUSTOM_VAR'
    ```
  </Step>
</Steps>

## Best practices

<CardGroup cols={2}>
  <Card title="Use login shells" icon="right-to-bracket">
    Start with `-l` to ensure your full environment is loaded.
  </Card>

  <Card title="Keep profiles fast" icon="gauge-simple-high">
    Optimize shell startup time by lazy-loading tools and plugins.
  </Card>

  <Card title="Export variables" icon="file-export">
    Always use `export` for variables that need to be available to child processes.
  </Card>

  <Card title="Test configurations" icon="flask">
    Test shell configurations before using them with OpenCode.
  </Card>
</CardGroup>