diff --git a/README.md b/README.md
index 103f145..055727e 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,128 @@
-Atlas Provider for Entity Framework Core
-=======================================
+# Atlas Provider for Entity Framework Core
 
+[![AtlasEF NuGet Package](https://img.shields.io/nuget/v/atlas-ef.svg)](https://www.nuget.org/packages/atlas-ef/) 
+
+Load [Entity Framework](https://learn.microsoft.com/en-us/ef/) schemas into an [Atlas](https://atlasgo.io) project.
+
+## Use-cases
+
+1. **Declarative migrations** - use a Terraform-like `atlas schema apply --env ef` command to apply your EF schema to the database.
+2. **Automatic migration planning** - use `atlas migrate diff --env ef` to automatically plan a migration from the current database version to the EF schema.
+
+## Installation
+
+**Windows:**
+
+Use PowerShell  to download the file:
+
+```powershell
+Invoke-WebRequest https://release.ariga.io/atlas/atlas-windows-amd64-latest.exe -OutFile atlas.exe
+```
+
+Then move the Atlas binary to a file location on your system PATH.
+
+**macOS + Linux:**
+
+```bash
+curl -sSf https://atlasgo.sh | sh
+```
+
+See [atlasgo.io](https://atlasgo.io/getting-started#installation) for more installation options.
+
+### AtlasEF Package
+
+Make sure to have a tool manifest available in your repository or create one using the following command:
+
+```bash
+dotnet new tool-manifest
+```
+
+Install the `AtlasEF` package from the command line:
+
+```bash
+dotnet tool install atlas-ef
+```
+
+Let's check if the tool is installed correctly:
+
+```bash
+dotnet atlas-ef --version
+```
+
+## Configuration
+
+By default, this tool will scan for implementation of the **DbContext** class in the current project and will generate a database schema based on it.
+
+This tool does not require a database connection, but it does need [Database Providers](https://learn.microsoft.com/en-us/ef/core/providers/?tabs=dotnet-core-cli) restored.
+
+### Setup Atlas
+
+In your project directory, create a new file named `atlas.hcl` with the following contents:
+
+```hcl
+data "external_schema" "ef" {
+  program = [
+    "dotnet",
+    "atlas-ef",
+  ]
+}
+
+env {
+  name = atlas.env
+  src = data.external_schema.ef.url
+  dev = "docker://mysql/8/dev" # list of dev dbs can be found here: https://atlasgo.io/concepts/dev-database
+  migration {
+    dir = "file://atlas-migrations"
+  }
+  format {
+    migrate {
+      diff = "{{ sql . \"  \" }}"
+    }
+  }
+}
+```
+
+### Usage
+
+Once you have the provider tool and Atlas configured, you can use them to manage your database schema.
+
+#### Apply
+
+You can use the `atlas schema apply` command to plan and apply a migration on your database from
+your current EF schema. This works by inspecting the target database schema and comparing it to the
+EF schema, creating a migration plan. Atlas will prompt you to confirm the migration plan
+before applying it to the database.
+
+> Note: For Windows users, you need to use the `atlas.exe` command instead of `atlas`.
+
+```bash
+atlas schema apply --env ef -u "mysql://root:password@localhost:3306/mydb"
+```
+
+The `-u` flag accepts the [URL](https://atlasgo.io/concepts/url) to the
+target database.
+
+#### Diff
+
+Atlas supports a [versioned migration](https://atlasgo.io/concepts/declarative-vs-versioned#versioned-migrations) 
+workflow, where each change to the database is versioned and recorded in a migration file. You can use the
+`atlas migrate diff` command to automatically generate a migration file that will migrate the database
+from its latest revision to the current EF schema.
+
+> Note: For Windows users, you need to use the `atlas.exe` command instead of `atlas`.
+
+```bash
+atlas migrate diff --env ef 
+```
+
+### Supported Databases
+
+The provider supports the following databases:
+* SQL Server
+* MySQL
+* PostgreSQL
+* SQLite
+
+### License
+
+This project is licensed under the [Apache License 2.0](LICENSE).
\ No newline at end of file