ASTO

A domain-specific language for organizing and documenting CLI commands - built in Rust.

Summary

• ASTO
  • Summary
  • 🤔 What is Asto?
  • 🙂🫴 Why Asto?
  • 🤨 Who is Asto for?
  • The Asto Syntax
  • Params with Asto
  • 📥 installation
  • 🧩 VS Code Extension
  • Exporting .asto files
    • Export to JSON
    • Export to MARKDOWN
• Project Name
  • Commands
    • fnd hi --name
    • Params
    • fnd bye --name
    • Params
  • Contribute
  • License

🤔 What is Asto?

Asto is a small but powerfull DSL designed to help CLI engineers organize, describe, and document command-line tools - clearly and efficiently.

Whether you're designing a new CLI or keeping track of a large one, Asto gives you a clean structure to define:

• Inputs
• Descriptions
• Output behavior
• Status/version
• Params/Actions
• Exportable documentation

🙂🫴 Why Asto?

• Minimal syntax
• Easy to read
• Fast to write
• Exportable to .json or .md
• Perfect for documenting CLI tools
• Designed for DevTools engineers
• Fully Offline
• Runs on Windows, Linux and macOS
• Built in Rust for performance

Asto is not a replacement for your CLI.
Asto is the language you use to structure it.

🤨 Who is Asto for?

• CLI engineer
• DevTools Creators
• Backend Developers
• Documenting Writers
• Anyone building command-line tools

The Asto Syntax

Using a fictional CLI called friend-cli (fnd).

friend_cli_commands.asto

> fnd hi --name
  / "Print 'Hi NAME'"
  : new
  {
    --name STRING "Username"
  }

> fnd bye --name
  / "Print 'Bye NAME'"
  : new
  {
    --name STRING "Username"
  }

Params with Asto

To use params, use --:

> fn hi --name

To specific param's type or what the param represents, use {}

For example:

> fn hi --name --lastname
  / "Print 'Hi name lastname'"
  : new
  {
      --name string "First name"
      --lastname string "Last name"
  }

The syntax is:

--param_name type "Description"

📥 installation

With Cargo

cargo install asto

Verify installation:

asto --version

Output:

asto vX.X.X

Without Cargo

Download the latest installer (.exe) from the releases page

🧩 VS Code Extension

Get syntax highlighting for your .asto files: gabrielxavier.Asto-Plugin (Search with this in vscode).

Exporting .asto files

Export to JSON

asto export friend_cli_command.asto --json

Output:

Asto CLI - "friend_cli_command.json" exported with successfully!

It generates:

friend_cli_command.json:

[
  {
    "node": "Input",
    "command": "fnd hi --name",
    "description": "Print 'Hi name'",
    "prefix": "fnd",
    "function": "hi",
    "version": "new",
    "params": [
      "--name"
    ],
    "params_config": [
      {
        "name": "--name",
        "typeval": "STRING",
        "desc": "Username"
      }
    ]
  },
  {
    "node": "Input",
    "command": "fnd bye --name",
    "description": "Print 'Bye name'",
    "prefix": "fnd",
    "function": "bye",
    "version": "new",
    "params": [
      "--name"
    ],
    "params_config": [
      {
        "name": "--name",
        "typeval": "STRING",
        "desc": "Username"
      }
    ]
  }
]

Export to MARKDOWN

asto export friend_cli_commands.asto --md

Asto CLI - "friend_cli_command.md" exported with successfully!

Output (friend_cli_commands.md):

Project Name

By: YOUR_NAME_HERE

Informations about project...

Commands

fnd hi --name

Say hi for someone

Status: 🟡 New

Params

• --name or -n (str): Username
  

fnd bye --name

Say bye for someone

Status: 🟡 New

Params

• --name or -n (str): Username
  

Contribute

1. Fork
2. Create Branch git branch -b my-improvement
3. Commit git commit -m "improve:: description of commands"
4. Push git push origin my-improvement
5. Open a PR

Ideas, docs, features and fixes are welcome.

License

MIT License - free to use, modify and integrate.