gitmobkab · gitmobkab · May 18, 2026 · May 18, 2026 · May 18, 2026 · May 18, 2026
diff --git a/.python-version b/.python-version
@@ -1 +1 @@
-3.13
+3.11
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.1] - 2026-05-18
+
+### Fixed
+
+- Fixed bugs when using the `run` command `--skip-config` and `--skip-confirm` flags.
+- Fixed json formatter to return proper json text
+- Fixed error message in the csv formatter
+
+### Changed
+
+- Downgrade minimum required python version to 3.11.
+- Updated the exits codes.
+- the generator suggestions system to be more forgiving
+
 ## [0.3.0] - 2026-05-15
 
 ### Added

diff --git a/docs/cli.md b/docs/cli.md
@@ -1,63 +1,74 @@
 # CLI Reference
 
-Copia is invoked from the command line. All commands share a common set of options for selecting the database profile and config file scope.
+When you install copia-seed, a command will be available on your shell.
+
+The command `copia` documented below.
 
 ---
 
 ## `copia`
 
-Launch the interactive TUI.
+The entrypoint of the cli app.
+
+Doesn't really do anything just print the version 
 
 ```bash
-copia [OPTIONS]
+copia [OPTIONS] COMMAND [ARGS]...
 ```
 
-**Options**
+### **Options**
 
-| Option | Short | Description |
+| Long name | Short name | Description |
 |--------|-------|-------------|
-| `--profile TEXT` | `-p` | Profile to use for the session. Defaults to `default`. |
-| `--global` | `-g` | Search only in the global config file. |
-| `--local` | `-l` | Search only in `.copia.toml` in the current directory. |
 | `--version` | `-v` | Display the current version and exit. |
+| `--install-completion` | | Install completion for the current shell. |
+| `--show-completion` | | Show completion for the current shell, to copy it or customize the installation. |
 | `--help` | `-h` | Display this message and exit. |
 
-**Examples**
 
-```bash
-# Launch with the default profile
-copia
+### **Commands**
 
-# Launch with a specific profile
-copia --profile staging
+| Name | Description |
+|------|-------------|
+| `init` | Generate a template config file for copia. |
+| `list` | List all profiles defined in both global and local config files. |
+| `tui` | Launch the interactive tui. |
+| `run` | Parse and run a file content. |
 
-# Force lookup in the global config only
-copia --global --profile "production db"
-```
 
-!!! note "Profile fallback"
-    When launching the TUI, copia silently falls back to the global config if the local profile is missing or invalid. [Use `copia list`](#copia-list) to inspect the state of both config files before launching.
+### Shell completion
+
+Copia supports shell completion via Typer.
+
+```bash
+# Install completion for your current shell
+copia --install-completion
+
+# Print the completion script without installing
+copia --show-completion
+```
 
+Supported shells: Bash, Zsh, Fish, PowerShell.
 ---
 
-## `copia init`
+## Commands
+
+### `copia init`
 
 Generate a template config file.
 
-```bash
-copia init [OPTIONS]
-```
+#### **Usage:** `copia init [OPTIONS]`
 
 By default, creates a local `.copia.toml` in the current directory.
 
-**Options**
+#### **Options**
 
-| Option | Short | Description |
+| Long name | Short name | Description |
 |--------|-------|-------------|
 | `--global` | `-g` | Create the config file in the global config directory instead. |
 | `--help` | `-h` | Display this message and exit. |
 
-**Examples**
+#### **Examples**
 
 ```bash
 # Create a local config file
@@ -69,21 +80,19 @@ copia init --global
 
 ---
 
-## `copia list`
+### `copia list`
 
 List all profiles defined across both global and local config files.
 
-```bash
-copia list
-```
+#### **Usage:** `copia list [OPTIONS]`
 
-**Options**
+#### **Options**
 
-| Option | Short | Description |
+| Long name | Short name | Description |
 |--------|-------|-------------|
 | `--help` | `-h` | Display this message and exit. |
 
-**Output**
+#### **Output**
 
 `copia list` reads both config files and displays all found profiles. It also reports issues it encounters:
 
@@ -92,7 +101,7 @@ copia list
 
 This makes `copia list` useful for debugging your config before launching the TUI.
 
-**Example**
+#### **Example**
 
 ```bash
 copia list
@@ -123,16 +132,141 @@ copia list
 
 ---
 
-## Shell completion
+### `copia tui`
 
-Copia supports shell completion via Typer.
+Launch the interactive tui.
+
+#### **Usage:** `copia tui [OPTIONS] [PROFILE_NAME]`
+
+#### **Arguments**
+
+| Name         | Type   | Description                                    | Default   |
+|--------------|--------|------------------------------------------------|-----------|
+| `profile_name` | `string` | the name of the profile to use for the session | `"default"` |
+
+
+#### **Options**
+
+| Long name | Short name | Description |
+|------|-------|-------------|
+| `--global` | `-g` | Search only in the global config |
+| `--local` | `-l` | Search only in the local config |
+| `--help` | `-h` | Show the help menu and exit |
+
+#### **Examples**
 
 ```bash
-# Install completion for your current shell
-copia --install-completion
+copia tui
 
-# Print the completion script without installing
-copia --show-completion
+copia tui staging
+
+copia tui -g # (1)!
+
+copia tui -g "mark-and-deceive" # (2)!
 ```
 
-Supported shells: Bash, Zsh, Fish, PowerShell.
+1. look for the profile named "default" **only** in the global config file
+2. look for the profile named "mark-and-deceive" **only** in the local config, no fallback to the global config
+
+
+### `copia run`
+
+Parse and run a file content
+
+#### **Usage:** `copia run [OPTIONS] [FILE]`
+
+#### **Arguments**
+
+| Name | Type | Description | Default |
+|------|------|-------------|---------|
+| `file` | `string` | the path of the file to parse and run | `"-"` |
+
+!!! tip "Using pipes to run a seed"
+    you can also directly pipe the content to parse via a pipe, when passing `"-"` as the file path.
+    `echo "uuid:uuid()" | copia run`
+
+#### **Options**
+
+| Long name | Short name | Type | Description | Default |
+|-----------|------------|------|-------------|---------|
+| `--table` | `-t` | `string` | the name of the table to commit to. mandatory without the --dumps flag. | |
+| `--profile` | `-p` | `string` | the name of the profile to use for the run. | `"default"` |
+| `--global` | `-g` | | search only in the global config | |
+| `--local` | `-l` | | search only in the local config | |
+| `--dumps` | `-d` | `("json", "csv", "sql")` | dumps the generated values based on the selected formatter | |
+| `--skip-config` | `-s` | | disable config lookup for the run. this will cause an error if the 'fetch' generator is detected. | |
+| `--rows` | `-n` | `integer >= 1` | the number of rows for the run. | `10` |
+| `--skip-confirm` | `-S` | | Skip the confirmation prompt. directly commit the values to the db. |
+| `--help` | `-h` | | Show the help menu and exit.
+
+
+#### **Examples** 
+
+- How to use the file argument
+
+```bash title="users.copia"
+id: uuid()
+name: name()
+age: int(0, 50)
+```
+
+```bash
+# launching a run with the file "users.copia"
+copia run --table users users.copia
+
+# using piping instead (implicit)
+cat users.copia | copia run --table users --skip-confirm
+
+# using piping instead (explicit)
+cat users.copia | copia run --table users --skip-confirm - # (1)!
+```
+
+1. 
+    - since we're using pipes. `--skip-confirm` will tell copia directly to commit.
+    This is required or you'll get an error!
+
+    - the `"-"` at the end tell copia to read from the pipes rather than expect a file path.
+
+
+!!! important "when the `--skip-confirm` flag is useful"
+    By default copia will show you a confirmation prompt to ask if you really want to commit the values.
+    This behavior is always going to lead to a crash/panic if you use a pipe for the input.
+    Adding the flag `--skip-confirm` flag will prevent this. useful when scripting too.
+
+- dumping rather than seeding
+
+```bash
+copia run --dumps json --skip-config users.copia # (1)!
+
+copia run --dumps sql users.copia # (2)!
+
+echo "user_id:fetch('users.id')" | copia run --dumps json --skip-config # (3)!
+```
+
+1. this will dumps the generated values in a json format and skip the config
+2. this will dumps but still perform the config lookup step
+3. this won't work because the `fetch generator` require a db connexion to work
+
+
+**Rules**
+
+1. the `--table` flag is mandatory if the `--dumps` flag is missing
+2. the `--skip-config` flag can only be used with the `--dumps` flag
+
+## Exit Codes
+
+Copia uses structured exit codes to make scripting and error handling predictable.
+
+| Code | Name | Description |
+|------|------|-------------|
+| `0` | `SUCCESS` | Everything went fine. |
+| `1` | `UNEXPECTED_ERROR` | An unplanned error occurred. |
+| `2` | `BAD_CLI_USAGE` | Invalid arguments, unknown options, or option values that fail validation. |
+| `3` | `BAD_DSL_INPUT` | The DSL input could not be parsed or validated. |
+| `4` | `VALIDATION_ERROR` | A resource failed validation — malformed config file, invalid profile, etc. |
+| `5` | `RESOURCE_ERROR` | A required external resource is missing — config file not found, missing dependency, etc. |
+| `6` | `CONNEXION_TO_DB_REFUSED` | The connection attempt to the database was refused. |
+| `7` | `GENERATION_ERROR` | An error occurred while generating values. |
+| `8` | `SEEDING_ERROR` | The insertion of generated rows into the database failed. |
+
+These codes are stable across versions and safe to use in scripts.
diff --git a/docs/configuration/index.md b/docs/configuration/index.md
@@ -51,6 +51,7 @@ The database adapter to use.
 | Value | Database |
 |-------|----------|
 | `"mysql"` | MySQL / MariaDB |
+| `"postgres"` | PostgreSQL
 
 ```toml
 adapter = "mysql"
@@ -130,10 +131,10 @@ user = "admin"
 password = "secret"
 ```
 
-Switch between profiles with the `--profile` flag:
+Switch between profiles with the `profile_name` argument:
 
 ```bash
-copia --profile staging
+copia tui staging
 ```
 
 ---
@@ -153,7 +154,9 @@ adapter = "mysql"
 Then referenced as:
 
 ```bash
-copia --profile "my profile"
+copia tui "my profile" # launch tui with the profile named "my profile"
+
+copia tui staging # launch the tui with the profile named staging
 ```
 
 ### Extra fields are forbidden
@@ -170,26 +173,13 @@ user = "root"
 timeout = 30  # ❌ not a valid field, copia will raise an error
 ```
 
-### ASCII constraint on `database` and `user`
-
-The `database` and `user` fields must contain ASCII characters only.
-Non-ASCII characters — including accented letters and Unicode — will be rejected:
-
-```toml
-user = "rené"   # ❌ invalid
-user = "rene"   # ✓
-```
-
-!!! note "This might change in the future"
-    The ASCII constraint is a temporary measure to ensure compatibility with all database servers. Future versions of Copia may remove this requirement.
-
 ## Editing the config file
 
 copia does not provide built-in commands for editing the config file. Use your preferred text editor to modify the TOML file directly.
 
 however if your IDE supports [taplo](https://taplo.tamasfe.dev/) or [Even Better TOML on vscode](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml).
 
-Add this line at the top of your `.copia.toml` or `profiles.toml`:
+Add this line at the top of your `.copia.toml` or `copia/profiles.toml`:
 
 ```toml
 #:schema https://raw.githubusercontent.com/gitmobkab/copia/main/docs/configuration/schema.json

diff --git a/docs/index.md b/docs/index.md
@@ -68,7 +68,7 @@ birthdate:  date_of_birth()
 
 # seed the posts table — references existing users
 id:      uuid()
-user_id: ref('users.id')
+user_id: fetch('users.id')
 body:    paragraph()
 date:    past_date()
 ```