added mdbook docs and updated docs/changelog

Author: razkar-studio

.github/workflows/deploy.yml

@@ -0,0 +1,55 @@
+# Sample workflow for building and deploying a mdBook site to GitHub Pages
+#
+# To get started with mdBook see: https://rust-lang.github.io/mdBook/index.html
+#
+name: Deploy mdBook site to Pages
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    env:
+      MDBOOK_VERSION: 0.5.2
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install mdBook
+        run: |
+          curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh
+          rustup update
+          cargo install --version ${MDBOOK_VERSION} mdbook
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+      - name: Build with mdBook
+        run: mdbook build
+        working-directory: docs
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs/book
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to vecli will be documented here.
 
+## [0.3.0] - 10/03/2026
+
+### Added
+- Subcommand chaining — commands can now nest arbitrarily deep (e.g. `app remote add`)
+- `Command::parent()` constructor for grouping commands with no handler of their own
+- `Command::subcommand()` builder method for attaching nested commands
+- `Command::print_help_if_no_args()` builder method for parent commands
+- `SUBCOMMANDS` section in command-level help output
+- `dispatch()` internal helper in `utils.rs` — recursive dispatch through the command tree
+- `prog` passed through dispatch for correct help output at any nesting depth
+
+### Changed
+- `Command::handler` is now `Option<fn(&CommandContext)>` — parent commands carry no handler
+- `Command::new()` still sets a handler; use `Command::parent()` when no handler is needed
+- `ctx.subcommand` is always the deepest matched command name, not the full path
+- `ctx.positionals` contains only tokens after the deepest matched command
+- `dispatch` moved to `utils.rs` and imported into `app.rs`, replacing the inline dispatch block in `run()`
+- Positional collection in `dispatch` now correctly skips flag values (not just flag names)
+
+### Fixed
+- Alias resolution now runs at each level of the command tree, not only at the app level
+- Parent commands with no handler and no `print_help_if_no_args` now print a clear error instead of silently returning
+
+---
+
 ## [0.2.0] - 09/03/2026
 
 ### Added

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "vecli"
-version = "0.2.0"
+version = "0.3.0"
 edition = "2024"
 description = "A zero-dependency, minimal CLI framework that's genuinely readable."
 license-file = "LICENSE.md"

Cargo.toml

@@ -1,4 +1,5 @@
 (this guide can also be found at the documentation)
+(this guide is deprecated. only trust docs.rs or the github pages site)
 
 A zero-dependency, minimal CLI framework that's genuinely readable, the tool you've been looking for.
 
@@ -16,7 +17,7 @@ which is the same as including it in your `Cargo.toml` file:
 
 ```toml
 [dependencies]
-vecli = "0.2"
+vecli = "0.3"
 ```
 
 ## Building Your First App

GUIDE.md

@@ -0,0 +1 @@
+book

docs/.gitignore

@@ -0,0 +1,9 @@
+[book]
+title = "vecli"
+authors = ["razkar-studio"]
+language = "en"
+src = "src"
+
+[output.html]
+site-url = "/vecli/"
+git-repository-url = "https://github.com/razkar-studio/vecli"

docs/book.toml

@@ -0,0 +1,16 @@
+# Summary
+
+[Introduction](README.md)
+
+# Getting Started
+- [Installation](getting-started/installation.md)
+- [Your First App](getting-started/first-app.md)
+  + [Configuring Your App](getting-started/configuring-your-app.md)
+
+# Core Concepts
+- [Commands](core-concepts/commands.md)
+  + [Subcommands](core-concepts/commands.md)
+- [Flags](core-concepts/flags.md)
+- [CommandContext](core-concepts/context.md)
+
+## More Soon!

docs/src/SUMMARY.md

@@ -0,0 +1,66 @@
+# Commands
+
+Let's give your app some commands to run. Here's how you can define them:
+
+```rust
+// use vecli::*;
+
+let hello_command = Command::new("hello", function_that_runs_on_hello /* fn(&CommandContext) */);
+
+// Adding this to the app:
+// App::new() ...
+    .add_command(hello_command)
+// ... .run();
+```
+
+The above is a simple command that runs when the user types the command `hello`, as in `my-app hello`.
+
+To actually make the command run, you need to define the function `function_that_runs_on_hello` that will be called when the command is executed.
+
+```rust
+fn function_that_runs_on_hello(_ctx: &CommandContext) {
+    println!("Hello!");
+}
+```
+
+Put two together, and you have a working app!
+
+```sh
+cargo run hello
+```
+
+That should print `Hello!` to the console.
+
+A shorter way to do this is to just directly define `Command` inside `.add_command()`:
+
+```rust
+App::new()
+    .add_command(Command::new("hello", function_that_runs_on_hello))
+// ... .run();
+```
+
+## Configuration
+
+Just like with the app itself, you can configure how the command is displayed on the help screen and usage output.
+
+For example, you can set the command's description and usage text:
+
+```rust
+Command::new("hello", function_that_runs_on_hello)
+    .description("Prints a friendly greeting")
+    .usage("<none>"); // a suffix to `my-app hello`
+```
+
+This will display the command's description and usage text when the user runs `my-app help` or `my-app hello --help`.
+
+The full configuration options for commands:
+- **`.description("Prints hello and exit.")`**: The description of the command, what it does.
+- **`.usage("[none]")`**: The usage for the command, will print alongside `my-app hello`.
+- `.strict_flags(true)`: If toggled, unknown flags will abort the program. We'll get to flags in a moment.
+
+*(Added in 0.3.0)*
+- `.print_help_if_no_args(true)`: If toggled, the help screen will be printed if no arguments (subcommands) are provided.
+
+---
+
+Okay, that was a lot to take in. Take a breather and let's continue. Say we want a `goodbye` subcommand that prints a farewell message. That's what we'll cover next on [Subcommands]().

docs/src/core-concepts/commands.md

@@ -0,0 +1,75 @@
+# CommandContext
+
+Every command handler receives a `&CommandContext` as its only argument. It contains everything
+vecli parsed from the command line for that invocation.
+
+```rust
+fn my_command(ctx: &CommandContext) {
+    // ctx is yours to use
+}
+```
+
+## Fields
+
+### `ctx.subcommand`
+
+The name of the command as typed by the user, e.g. `"add"` or `"list"`.
+
+```rust
+println!("Running: {}", ctx.subcommand);
+```
+
+### `ctx.positionals`
+
+A `Vec<String>` of all non-flag tokens that followed the subcommand, in order.
+
+```sh
+mytool add "buy milk" groceries
+# ctx.positionals == ["buy milk", "groceries"]
+```
+
+```rust
+let task = ctx.positionals.first().map(String::as_str).unwrap_or("unnamed");
+```
+
+### `ctx.flags`
+
+A `HashMap<String, String>` of all flags passed by the user, keyed by canonical name after alias
+resolution. Boolean flags (no explicit value) have the value `"true"`.
+
+```sh
+mytool add "buy milk" --priority high -v
+# ctx.flags == { "priority": "high", "verbose": "true" }
+```
+
+```rust
+if ctx.flags.contains_key("verbose") {
+    println!("verbose mode");
+}
+
+let priority = ctx.flags.get("priority").map(String::as_str).unwrap_or("medium");
+```
+
+Global flags registered on the app are merged in automatically — no extra setup needed in the handler.
+
+## Full Example
+
+```rust
+fn add(ctx: &CommandContext) {
+    let task = ctx.positionals.first().map(String::as_str).unwrap_or("unnamed");
+    let priority = ctx.flags.get("priority").map(String::as_str).unwrap_or("medium");
+
+    if ctx.flags.contains_key("verbose") {
+        println!(
+            "[verbose] subcommand='{}', positionals={:?}, flags={:?}",
+            ctx.subcommand, ctx.positionals, ctx.flags
+        );
+    }
+
+    println!("Added '{}' with priority {}.", task, priority);
+}
+```
+
+---
+
+If you've been this far from the beginning, congrats! This doc is under production and you've reached the end... for now. More guides will be added soon! For now, read the API reference at [docs.rs](https://docs.rs/vecli).