oxid init

Initialize an Oxid workspace. Downloads providers, creates the local state database, and optionally imports existing Terraform state.

Usage

oxid init

The init command prepares your working directory for use with Oxid. It reads your .tf files, resolves provider requirements, downloads provider binaries, and creates the local state database.

What It Does

1. Creates the .oxid/ directory

Oxid stores all local state and cached binaries in a .oxid/ directory at the root of your workspace:

.oxid/
  oxid.db          # SQLite state database
  providers/       # Cached provider binaries
    registry.terraform.io/
      hashicorp/
        aws/
          6.32.1/
            terraform-provider-aws

TipAdd .oxid/ to your .gitignore. The state database and provider binaries should not be committed.

2. Downloads providers from registry.terraform.io

Oxid reads your required_providers block and downloads each provider binary from the official Terraform registry. Providers are cached in .oxid/providers/ and reused on subsequent runs.

main.tf

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

$ oxid init

Initializing Oxid workspace...
  Downloading hashicorp/aws v5.67.0 for darwin_arm64...
  Provider cached: .oxid/providers/registry.terraform.io/hashicorp/aws/5.67.0/terraform-provider-aws

Oxid initialized successfully.

3. Creates the SQLite state database

On first init, Oxid creates a SQLite database at .oxid/oxid.db with tables for resources, outputs, dependencies, runs, and resource history. This database is queryable with oxid query.

4. Auto-imports from terraform.tfstate

If a terraform.tfstate file is present in the working directory, Oxid automatically imports all resources into its state database during init. This makes migration from Terraform seamless.

$ oxid init

Initializing Oxid workspace...
  Found terraform.tfstate - importing 47 resources...
  Imported: aws_vpc.main
  Imported: aws_subnet.public[0]
  Imported: aws_subnet.public[1]
  ...
  Successfully imported 47 resources from Terraform state.

Oxid initialized successfully.

5. Imports from S3 remote backend

If your Terraform configuration defines an S3 backend, Oxid can fetch the remote state file and import resources from it:

backend.tf

terraform {
  backend "s3" {
    bucket = "my-terraform-state"
    key    = "prod/terraform.tfstate"
    region = "us-east-1"
  }
}

NoteOxid uses your AWS credentials (environment variables or shared credentials file) to access the S3 bucket. Ensure you have read access to the state file.

Flags

Flag	Description	Default
--config <path>	Path to the configuration directory. Defaults to the current working directory.	.

Re-running init

Running oxid init again is safe. It will:

Download any new or updated providers
Skip providers that are already cached at the correct version
Re-import from terraform.tfstate if present (upsert - existing resources are updated)
Not destroy or reset your existing Oxid state

Examples

Initialize in a subdirectory

oxid init --config ./environments/production

Initialize a fresh project

mkdir my-infra && cd my-infra
cat > main.tf << 'EOF'
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  region = "us-west-2"
}

resource "aws_s3_bucket" "data" {
  bucket = "my-data-bucket"
}
EOF

oxid init
oxid plan