diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index c846c1c..066f58e 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -64,9 +64,11 @@ jobs:
     needs: artifacts
     steps:
       - uses: actions/checkout@v4
+      
       - name: install dependencies
+        # We use the cloud CLIs github packages in their [default runner images](https://github.com/actions/runner-images).
+        # The runner images miss terraform, so we use chocolatey to install those quickly here.
         uses: crazy-max/ghaction-chocolatey@v3
-        # note: all other dependencies are installed in the image already
         with:
           args: install --force terraform terragrunt terraform-docs
       - name: install collie
@@ -91,9 +93,10 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: install dependencies 
-        # note: we forego default.nix and to be as close to a realistic user experience as possible.
-        # unfortunately ubuntu doesn't package terraform and related tools very well, so we use nix for those.
-        # All the other dependencies are already present on the runner images, so we use those.
+        # note: we forego using the flake.nix development environment and try to be as close to a realistic user experience as possible.
+        # This means that we use the cloud CLIs github packages in their [default runner images](https://github.com/actions/runner-images).
+        # The runner images miss terraform and unfortunately ubuntu doesn't package it and related tools very well, 
+        # so we abuse nix to install those quickly here.
         uses: cachix/install-nix-action@v22
         with:
           nix_path: nixpkgs=channel:nixos-unstable
@@ -116,12 +119,9 @@ jobs:
     needs: artifacts
     steps:
       - uses: actions/checkout@v4
-        # note: we forego default.nix and to be as close to a realistic user experience as possible
-        # all the other dependencies are already present on the runner images, so we use those
-        # and just install the missing ones via nix, as these are not available in standard uubunt
-        # note: we forego default.nix and to be as close to a realistic user experience as possible
-        # and just install the missing ones via brew as many of our users would do
-        # all the other dependencies are already present on the runner images, so we use those
+        # note: we forego using the flake.nix development environment and try to be as close to a realistic user experience as possible.
+        # This means that we use the cloud CLIs github packages in their [default runner images](https://github.com/actions/runner-images).
+        # The runner images miss terraform so we use a standard brew command to install them here
       - name: install dependencies
         run: brew install terraform terragrunt terraform-docs
       - name: run test
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7b51128..2253565 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,11 +4,12 @@
 
 ### nix-shell
 
-You can use the provided `default.nix` file to stand up a
-[nix-shell](https://nixos.org/manual/nix/stable/command-ref/nix-shell.html)
-containing all dependencies required for developing collie, including the cloud
-CLIs (aws, az, gcloud). Using the nix-shell is _optional_, you can of course use
-it as a recipe for installing depencies with your package manager of choice.
+You can use the provided `flake.nix` file to stand up a
+[nix-develop](https://nix.dev/manual/nix/2.18/command-ref/new-cli/nix3-develop)
+shell containing all dependencies required for developing collie, including the
+cloud CLIs (aws, az, gcloud). Using the nix develop shell is _optional_, you can
+of course use it as a recipe for installing depencies with your package manager
+of choice.
 
 ### Git Hooks
 
diff --git a/default.nix b/default.nix
deleted file mode 100644
index faf6745..0000000
--- a/default.nix
+++ /dev/null
@@ -1,34 +0,0 @@
-{ pkgs ? import <nixpkgs> { }
-, unstable ? import <nixpkgs-unstable> {
-    config.allowUnfree = true;
-  }
-}:
-
-pkgs.mkShell {
-  NIX_SHELL = "collie-cli";
-  shellHook = ''
-    echo starting collie-cli dev shell
-  '';
-
-  buildInputs = [
-    pkgs.deno
-
-    # used for build scripts
-    pkgs.unzip
-    pkgs.gnused
-
-    # cloud provider clis
-    pkgs.awscli2
-    pkgs.azure-cli
-    pkgs.google-cloud-sdk
-
-    # terraform
-    pkgs.terraform
-    pkgs.terragrunt
-    pkgs.tflint
-    pkgs.terraform-docs
-
-    # for collie foundation docs
-    pkgs.nodejs
-  ];
-}
diff --git a/flake.lock b/flake.lock
new file mode 100644
index 0000000..312dbcd
--- /dev/null
+++ b/flake.lock
@@ -0,0 +1,27 @@
+{
+  "nodes": {
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1724531977,
+        "narHash": "sha256-XROVLf9ti4rrNCFLr+DmXRZtPjCQTW4cYy59owTEmxk=",
+        "owner": "nixos",
+        "repo": "nixpkgs",
+        "rev": "2527da1ef492c495d5391f3bcf9c1dd9f4514e32",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nixos",
+        "ref": "nixos-24.05",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}
diff --git a/flake.nix b/flake.nix
new file mode 100644
index 0000000..1db0ccf
--- /dev/null
+++ b/flake.nix
@@ -0,0 +1,53 @@
+{
+  description = "Flake for collie-cli";
+
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-24.05";
+  };
+
+
+  outputs = { self, nixpkgs }:
+
+    let
+      shellsForSystem = system:
+        let
+          pkgs = import nixpkgs { inherit system; config.allowUnfree = false; };
+        in
+        {
+          default = pkgs.mkShell {
+            name = "collie-cli";
+            packages = with pkgs;
+              [
+                deno
+
+                # used for build scripts
+                unzip
+                gnused
+
+                # cloud provider clis
+                awscli2
+                azure-cli
+                google-cloud-sdk
+
+                # terraform
+                opentofu
+                terragrunt
+                tflint
+                terraform-docs
+
+                # for collie foundation docs
+                nodejs
+              ];
+          };
+        };
+
+
+    in
+    {
+      devShells = {
+        aarch64-darwin = (shellsForSystem "aarch64-darwin");
+        x86_64-darwin = (shellsForSystem "x86_64-darwin");
+        x86_64-linux = (shellsForSystem "x86_64-linux");
+      };
+    };
+}