Jules PR

docs/content/docs/cli/command-overview.mdx

@@ -0,0 +1,48 @@
+---
+title: Command Overview
+description: An overview of all available CLI commands
+---
+
+The Restflow CLI is the primary way to execute your API tests. The base command is `restflow`.
+
+You can get help at any time by running:
+```bash
+restflow --help
+```
+
+### Main Commands
+
+Restflow has a few main commands for different tasks.
+
+#### `restflow run`
+
+This is the most important command. It is used to execute one or more `.flow` files.
+
+```bash
+# Run a single flow
+restflow run path/to/your.flow
+
+# Run all flows in a directory
+restflow run path/to/your/flows/
+```
+
+This command has many options for controlling the execution, which are detailed on the `run` command page.
+
+#### `restflow init`
+
+The `init` command helps you set up a new Restflow project or add Restflow to an existing one. It can create a sample project structure with example flows and an environment file.
+
+```bash
+# Initialize a new Restflow project in the current directory
+restflow init
+```
+
+This is a great way to get started quickly.
+
+### Global Options
+
+These options can be used with any command.
+
+- `--help`: Show help information.
+- `--version`: Show the installed version of Restflow.
+- `--verbose`: Enable detailed logging, which can be useful for debugging.

docs/content/docs/cli/meta.json

@@ -0,0 +1,7 @@
+{
+  "title": "CLI Reference",
+  "pages": [
+    "command-overview",
+    "run-command"
+  ]
+}

docs/content/docs/cli/run-command.mdx

@@ -0,0 +1,72 @@
+---
+title: The 'run' Command
+description: Running flows with various options
+---
+
+The `restflow run` command is used to execute your `.flow` files. You can specify one or more files or directories as arguments.
+
+### Basic Usage
+
+```bash
+# Run a single flow file
+restflow run my-test.flow
+
+# Run multiple specific flow files
+restflow run test1.flow test2.flow
+
+# Run all flow files in a directory (and its subdirectories)
+restflow run ./tests/
+```
+
+### Command Options
+
+The `run` command has several options to customize its behavior.
+
+#### `--env <path>` or `-e <path>`
+
+Load environment variables from a specific file.
+
+```bash
+restflow run tests/ --env .env.staging
+```
+
+#### `--format <format>` or `-f <format>`
+
+Specify the output format.
+- `console` (default): Human-readable, colored output.
+- `json`: Machine-readable JSON output.
+- `summary`: A concise table of results.
+
+```bash
+restflow run tests/ --format json > results.json
+```
+
+#### `--timeout <ms>`
+
+Set a timeout in milliseconds for each HTTP request. The default is typically 30 seconds (30000 ms).
+
+```bash
+# Set a 10-second timeout
+restflow run tests/ --timeout 10000
+```
+
+#### `--show-body`
+
+Include the request and response bodies in the output. This is very useful for debugging.
+
+#### `--show-headers`
+
+Include the request and response headers in the output.
+
+#### `--verbose`
+
+Enable verbose logging for more detailed output about the execution process.
+
+### Combining Options
+
+You can combine these options to suit your needs.
+
+```bash
+# Run tests against staging, with a 5s timeout, and show bodies and headers
+restflow run tests/ --env .env.staging --timeout 5000 --show-body --show-headers
+```

docs/content/docs/core-concepts/assertions-basics.mdx

@@ -0,0 +1,68 @@
+---
+title: Assertions Basics
+description: Writing basic assertions and validations
+---
+
+Assertions are used to verify that your API is behaving as expected. In Restflow, you use the `assert` directive to check the status code, headers, and body of a response.
+
+### The `assert` Directive
+
+The `assert` directive has the following structure:
+
+`> assert <source> <operator> <value>`
+
+- **source**: The part of the response to check (e.g., `status`, `body.id`, `headers["content-type"]`).
+- **operator**: The comparison to perform (e.g., `==`, `!=`, `>`, `contains`).
+- **value**: The expected value.
+
+If an assertion fails, the step is marked as failed, and the execution of the flow may stop depending on your configuration.
+
+### Common Assertions
+
+Here are some of the most common assertions you'll use:
+
+#### Checking the Status Code
+
+This is the most fundamental assertion. You should almost always check the status code.
+
+```flow
+### Get a resource
+GET https://api.example.com/items/1
+
+> assert status == 200
+```
+
+#### Checking the Response Body
+
+You can use JSONPath to access values in a JSON response body.
+
+```flow
+### Get a user
+GET https://api.example.com/users/123
+
+> assert body.id == 123
+> assert body.name == "John Doe"
+> assert body.address.city == "New York"
+```
+
+#### Checking for Existence
+
+You can check if a field exists in the response.
+
+```flow
+> assert body.id != null
+```
+
+#### Checking Array Length
+
+```flow
+> assert body.items.length > 0
+```
+
+#### Checking Headers
+
+```flow
+> assert headers["content-type"] contains "application/json"
+```
+
+These are just the basics. The "DSL Reference" section has a complete guide to all the available assertion operators and advanced techniques.

docs/content/docs/core-concepts/dsl-basics.mdx

@@ -0,0 +1,48 @@
+---
+title: DSL Basics
+description: Introduction to the .flow file syntax
+---
+
+The Restflow DSL (Domain-Specific Language) is designed to be simple, readable, and easy to write. All tests are written in `.flow` files using a plain text format.
+
+### Basic Structure
+
+A `.flow` file is composed of one or more steps. Each step has the following structure:
+
+```
+### Step Name
+HTTP_METHOD URL
+Header-Name: Header-Value
+
+Request Body
+
+> directive
+```
+
+- **Step Name**: A descriptive name for your step, starting with `###`.
+- **HTTP Method and URL**: The HTTP method (e.g., `GET`, `POST`) and the endpoint URL.
+- **Headers**: Optional HTTP headers, one per line.
+- **Request Body**: The body of the request, separated from the headers by a blank line.
+- **Directives**: Actions to perform after the request, such as assertions or capturing variables. Each directive starts with `>`.
+
+### Example
+
+Here's a complete example of a `.flow` file with a single step:
+
+```flow
+### Create a new user
+POST https://api.example.com/users
+Content-Type: application/json
+Authorization: Bearer {{api_key}}
+
+{
+  "name": "John Doe",
+  "email": "john.doe@example.com"
+}
+
+> assert status == 201
+> assert body.id != null
+> capture userId = body.id
+```
+
+This example demonstrates all the basic components of the DSL in action. As you can see, it's designed to be self-documenting and easy to understand at a glance.

docs/content/docs/core-concepts/environment-management.mdx

@@ -0,0 +1,48 @@
+---
+title: Environment Management
+description: Managing environments and configurations
+---
+
+Real-world API testing requires running the same tests against different environments, such as development, staging, and production. Restflow makes this easy with its support for `.env` files.
+
+### What is an `.env` file?
+
+An `.env` file is a simple text file that contains key-value pairs for your environment-specific variables.
+
+Here is an example `.env` file:
+
+```dotenv
+# .env.staging
+BASE_URL=https://staging.api.example.com
+API_KEY=staging-secret-key
+TEST_USER=staging_user
+```
+
+### Using Environment Variables
+
+You can use the variables from your `.env` file in your flows using the `{{variable_name}}` syntax.
+
+```flow
+### Get data from a protected endpoint
+GET {{BASE_URL}}/data
+Api-Key: {{API_KEY}}
+
+> assert status == 200
+```
+
+### Running with an Environment
+
+To run your flows with a specific environment file, use the `--env` flag on the command line:
+
+```bash
+restflow run my-flow.flow --env .env.staging
+```
+
+When you run this command, Restflow will load the variables from `.env.staging` and make them available in your flow.
+
+This allows you to keep your `.flow` files clean and free of environment-specific details. You can have multiple `.env` files for your different environments:
+- `.env.dev`
+- `.env.staging`
+- `.env.prod`
+
+And switch between them easily using the `--env` flag. This is a powerful feature for creating portable and maintainable API tests.

docs/content/docs/core-concepts/flows-and-steps.mdx

@@ -0,0 +1,45 @@
+---
+title: Flows and Steps
+description: Understanding the basic structure of Restflow tests
+---
+
+In Restflow, your API tests are organized into **flows** and **steps**. This structure helps you create readable, maintainable, and powerful tests.
+
+### Flows
+
+A **flow** is a single `.flow` file that contains a sequence of steps. It represents a complete user journey or a set of related API tests. For example, a `login.flow` file could contain all the steps required to authenticate a user.
+
+Flows are executed from top to bottom. You can run a single flow or multiple flows at once.
+
+### Steps
+
+A **step** is a single API request within a flow. Each step has a name, an HTTP request, and optional directives for assertions and variable capturing.
+
+A step is defined using `###` followed by the step name.
+
+Here is an example of a flow with two steps:
+
+```flow
+### Step 1: Get a post
+GET https://jsonplaceholder.typicode.com/posts/1
+
+> assert status == 200
+
+### Step 2: Create a new post
+POST https://jsonplaceholder.typicode.com/posts
+Content-Type: application/json
+
+{
+  "title": "My new post",
+  "body": "A great post"
+}
+
+> assert status == 201
+```
+
+In this example:
+- The file itself represents the flow.
+- "Get a post" is the first step.
+- "Create a new post" is the second step.
+
+Each step is independent by default, but you can use variables to pass data between steps, creating powerful testing workflows.

docs/content/docs/core-concepts/meta.json

@@ -0,0 +1,10 @@
+{
+  "title": "Core Concepts",
+  "pages": [
+    "flows-and-steps",
+    "dsl-basics",
+    "variables-overview",
+    "assertions-basics",
+    "environment-management"
+  ]
+}