> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ubiquex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install ubx and its prerequisites.

## Prerequisites

<AccordionGroup>
  <Accordion title="Go 1.21+">
    ```bash theme={null}
    brew install go
    go version  # go1.21.0 or later
    ```

    Or download from [golang.org/dl](https://golang.org/dl/).
  </Accordion>

  <Accordion title="Pulumi CLI">
    ```bash theme={null}
    brew install pulumi/tap/pulumi
    pulumi version
    ```

    Or see [Pulumi install docs](https://www.pulumi.com/docs/install/).
  </Accordion>

  <Accordion title="Node.js 18+">
    ```bash theme={null}
    brew install node
    node --version  # v18.x.x or later
    ```
  </Accordion>

  <Accordion title="Cloud credentials">
    Configure credentials using `ubx auth`:

    ```bash theme={null}
    ubx auth aws     # runs aws configure
    ubx auth gcp     # runs gcloud auth application-default login
    ubx auth azure   # runs az login
    ubx auth status  # check all providers
    ```
  </Accordion>
</AccordionGroup>

## Install ubx

```bash theme={null}
go install github.com/ubiquex/ubx@latest
```

Verify:

```bash theme={null}
ubx version
# ubx v1.0.0
```

## Shell Completion

<Tabs>
  <Tab title="bash">
    ```bash theme={null}
    # Current session
    source <(ubx completion bash)

    # Permanently (Linux)
    ubx completion bash > /etc/bash_completion.d/ubx

    # Permanently (macOS + Homebrew)
    ubx completion bash > $(brew --prefix)/etc/bash_completion.d/ubx
    ```
  </Tab>

  <Tab title="zsh">
    ```bash theme={null}
    source <(ubx completion zsh)
    # Permanently:
    ubx completion zsh > "${fpath[1]}/_ubx"
    ```
  </Tab>

  <Tab title="fish">
    ```bash theme={null}
    ubx completion fish > ~/.config/fish/completions/ubx.fish
    ```
  </Tab>

  <Tab title="PowerShell">
    ```powershell theme={null}
    ubx completion powershell | Out-String | Invoke-Expression
    ```
  </Tab>
</Tabs>

## Project Config (`ubx.yaml`)

```yaml theme={null}
project:     my-platform
backend:     file://.ubx/state   # local state (default)
defaultEnv:  dev
ubx_version: ">= 1.0.0"         # optional version constraint

# Default tags applied to all taggable resources
default_tags:
  env:     "${input.env}"
  managed: "ubx"

# AI features (optional)
# ai:
#   enabled: true
#   api_key: "sk-ant-..."   # or set UBX_AI_API_KEY env var
#   model: "claude-haiku-4-5"
#   features:
#     plan_summary: true
#     cost_estimate: true
```

## Version Constraints

```yaml theme={null}
ubx_version: ">= 1.0.0"
# or a range:
ubx_version: ">= 1.0.0, < 2.0.0"
```

If the constraint is not satisfied:

```
✗  ubx version constraint not satisfied
   required: >= 1.0.0
   running:  0.9.0
   upgrade ubx to continue: go install github.com/ubiquex/ubx@latest
```

## Ignoring Files

Create a `.ubxignore` at the project root to exclude files from compilation:

```
# .ubxignore
generated/
vendor/
**/*.test.iac
envs/prod/*.iac
```

Follows gitignore semantics. The `.ubx/` directory is always excluded regardless.