From 91e8dec3c4ebb664f715441bf892ff56945ee7dd Mon Sep 17 00:00:00 2001 From: Dario Ghilardi Date: Thu, 5 Feb 2026 10:45:14 +0100 Subject: [PATCH 1/2] fix(README): rewording for clarity --- README.md | 115 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 85 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index eede457..fbe9c34 100644 --- a/README.md +++ b/README.md @@ -1,54 +1,95 @@ -# NablaFlow CLI   [![built with nix](https://builtwithnix.org/badge.svg)](https://builtwithnix.org) +# nf - The NablaFlow CLI   [![built with nix](https://builtwithnix.org/badge.svg)](https://builtwithnix.org) + +A command-line interface for creating simulations on AeroCloud and ArchiWind. ## Installation -### As flake +### Stand-alone (Linux, macOS, Windows) + +#### Linux/MacOS + +```bash +curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nablaflow/cli/releases/download/v1.1.0/nf-installer.sh | sh +``` + +#### Windows + +```bash +powershell -ExecutionPolicy Bypass -c "irm https://github.com/nablaflow/cli/releases/download/v1.1.0/nf-installer.ps1 | iex" +``` + +### As flake (Nix users) Can be run directly via `nix run https://github.com/nablaflow/cli`. -### Stand-alone (Linux, macOS, Windows) +## Getting started -Follow instructions in [releases](https://github.com/nablaflow/cli/releases). +After installing the CLI, open the terminal and run the `nf -V` command to verify it's correctly installed. -## Usage +In order to use the CLI, a personal access token is required. Head to your [AeroCloud API settings page](https://aerocloud.nablaflow.io/developer/api) and generate one with read and write permissions. The token should never be shared; keep it safe because it grants access to your account data. -> [!TIP] -> All commands accept `--json` after `nf` to output JSON instead of human readable text, so that the CLI can be comfortably used in scripts. +Configure the CLI with the generated token by running: -> [!TIP] -> Use `--help` on every subcommand to see their documentation. +```bash +nf aerocloud set-auth-token $TOKEN +``` -> [!TIP] -> All commands that consume a JSON from a path also accept JSON from stdin, be sure to pass `-` instead of the file. -> This facilitates usage from scripts. +### Working with projects -## Aerocloud +Commands below use `v7` to target the AeroCloud API version. -As NablaFlow's API requires authentication, you first need to [get a personal access token](https://aerocloud.nablaflow.io/developer/api). -Once you have one, set it using `nf aerocloud set-auth-token $TOKEN`. +To list the existing projects: +```bash +nf aerocloud v7 list-projects +``` + +To create a new project: +```bash +nf aerocloud v7 create-project "project name" +``` -### AeroCloud v7 +### Creating a model -In order to submit a simulation you need a project and a model: -- `nf aerocloud v7 list-projects` or `nf aerocloud v7 create-project "project name"`, note down the project ID. -- `nf aerocloud v7 create-model $PATH_TO_JSON`, see [examples/aerocloud/v7/create_model.json](examples/aerocloud/v7/create_model.json) as starting point. - Note down the model id. -- `nf aerocloud v7 create-simulation --model-id $MODEL_ID --project-id $PROJECT_ID $PATH_TO_JSON`, see [examples/aerocloud/v7/create_simulation.json](examples/aerocloud/v7/create_simulation.json) as starting point. +To create a model, start by defining a JSON manifest for it, see [examples/aerocloud/v7/create_model.json](examples/aerocloud/v7/create_model.json) as starting point. -#### Batch +Then run: +```bash +nf aerocloud v7 create-model $PATH_TO_JSON +``` -`nf aerocloud v7 batch $dir` provides an interactive UI to review and submit a batch of simulations. +### Creating a simulation -Inside the UI, follow the instructions and available commands at the bottom of each block. +To create a simulation you need: +- a target project +- an input model -> [!TIP] -> When submitting simulations, stuff can go wrong: network timeouts, invalid parameters and such. -> Each succesfully submitted simulation will be marked as such and won't be resent, while allowing you to make changes to JSON files - and reload them. +Follow the instructions in the previous steps to create both, note down project ID and model ID. -The expected structure of the passed `$dir` is: +Then define a JSON manifest for it, see [examples/aerocloud/v7/create_simulation.json](examples/aerocloud/v7/create_simulation.json) as starting point. +Then run: + +```bash +nf aerocloud v7 create-simulation --model-id $MODEL_ID --project-id $PROJECT_ID $PATH_TO_JSON ``` + +> [!TIP] +> All commands accept `--json` after `nf` to output JSON instead of human readable text, so that the CLI can be comfortably used in scripts. + +> [!TIP] +> Use `--help` on every subcommand to see their documentation. + +> [!TIP] +> All commands that consume a JSON from a path also accept JSON from stdin, be sure to pass `-` instead of the file. +> This facilitates usage from scripts. + +### Batch mode + +The CLI can be used in batch mode to create multiple simulations at once. + +First, prepare a folder with the JSON manifests for your simulation and the models to upload. Use the following structure as an example: + +```text dir ├── simulation-1 # `simulation-1` is going to be the name of the simulation. │   ├── model-1.stl # `model` can be any valid UTF-8 filename. @@ -62,4 +103,18 @@ dir ├── params.json ``` -You can find an example under [examples/aerocloud/v7/batch](examples/aerocloud/v7/batch) +An example is available under [examples/aerocloud/v7/batch](examples/aerocloud/v7/batch). + +With the folder ready, run the following command to enter the Batch mode: + +```bash +nf aerocloud v7 batch $directory +``` + +An interactive UI will be started where you can review and submit your simulations. + +Follow the instructions and available commands at the bottom of the user interface. + +> [!TIP] +> When submitting simulations, stuff can go wrong: network timeouts, invalid parameters and such. +> Each successfully submitted simulation will be marked as such and won't be resent, while allowing you to make changes to JSON files and reload them. From 4fe45655942366be77f6f7b9c02d20a55f39d1be Mon Sep 17 00:00:00 2001 From: Dario Ghilardi Date: Thu, 5 Feb 2026 14:44:12 +0100 Subject: [PATCH 2/2] fix(readme): cachix usage Co-authored-by: Federico Ravasio --- README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index fbe9c34..6185ad4 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,11 @@ powershell -ExecutionPolicy Bypass -c "irm https://github.com/nablaflow/cli/rele ### As flake (Nix users) -Can be run directly via `nix run https://github.com/nablaflow/cli`. +Can be run directly using + +```bash +cachix use nablaflow-public +nix run github:nablaflow/cli/v1.1.0 ## Getting started