feat: a scriptable CLI with experiment, model and artifact commands

Cargo.toml

@@ -22,17 +22,17 @@ anyhow = "1.0.104"
 toml = "0.8.23"
 toml_edit = "0.22.27"
 clap = { version = "4.6.4", features = ["derive", "cargo"] }
-colored = "3.1.1"
 derive-new = { version = "0.7.0", default-features = false }
 tracing = "0.1.44"
 serde = { version = "1.0.229", default-features = false, features = ["derive"] }
 serde_json = "1.0.151"
 sha2 = { version = "0.10.9" }
 thiserror = "2.0.19"
 env_logger = "0.11.11"
-console = "0.15.11"
-cliclack = "0.3.8"
-directories = "5.0"
+console = "0.16.4"
+cliclack = "0.5.6"
+supports-hyperlinks = "3.2.0"
+webbrowser = "1.2.4"
 url = "2.5.8"
 cargo_metadata = { version = "0.20.0", features = ["builder"] }
 flate2 = { version = "1.1.9", default-features = false, features = ["zlib"] }
@@ -45,10 +45,12 @@ gix = { version = "0.77.0", default-features = false, features = [
 ] }
 chrono = "0.4.45"
 strum = { version = "0.27.2", features = ["derive"] }
+tempfile = "3.27.0"
+rstest = { version = "0.27.0", default-features = false }
 
 
 ## External Crate
-tracel-client = "0.20.0"
+tracel-client = { git = "https://github.com/tracel-ai/burn-central-client", rev = "5a618779e8b9288f51415da6af4f385194b6e950" }
 
 ## Crate
 tracel-cli = { version = "0.5.0", path = "crates/tracel-cli" }

README.md

@@ -11,174 +11,190 @@
 
 </div>
 
-## Description
+The Tracel CLI (`tracel`) works with the
+[Tracel Console](https://console.tracel.ai/), where
+[Burn](https://github.com/tracel-ai/burn) users track experiments, share models
+and run training on compute providers. Together with the
+[Tracel SDK](https://github.com/tracel-ai/tracel) in your project, it lets you:
 
-The Tracel CLI (`tracel`) is the command-line tool for interacting with [Tracel Console](https://console.tracel.ai/), the centralized platform for experiment tracking, model sharing, and deployment for [Burn](https://github.com/tracel-ai/burn) users.
-
-This CLI works in conjunction with the [Tracel SDK](https://github.com/tracel-ai/tracetracell) to provide a seamless workflow for:
-
-- Running training jobs locally or remotely
-- Managing experiments and tracking metrics
-- Packaging and deploying models
-- Integrating with compute providers
-- Managing project configurations
+- run your project locally and browse its experiments, metrics and logs;
+- package your code for compute providers;
+- push, pull and promote models, and download artifacts and datasets.
 
 ## Installation
 
-### Install from crates.io
-
 ```bash
 cargo install tracel-cli
 ```
 
-### Build from source
+Or build it from source:
 
 ```bash
 git clone https://github.com/tracel-ai/tracel-cli.git
 cd tracel-cli
 cargo install --path crates/tracel-cli
 ```
 
-After installation, the `tracel` command will be available in your terminal.
+You need Rust 1.87 or later, an account on the
+[Tracel Console](https://console.tracel.ai/), and the Tracel SDK in your Burn
+project.
 
-## Prerequisites
+## Getting started
+
+```bash
+tracel login      # approve the login in your browser
+tracel init       # link this workspace to a Console project
+tracel train      # run it locally with `cargo run`
+tracel experiments list
+```
 
-1. **Tracel Account**: Create an account at [console.tracel.ai](https://console.tracel.ai/)
-2. **Rust**: Version 1.87.0 or higher
-3. **Tracel SDK**: Add the SDK to your Burn project
+Every command takes `--help`. Commands print tables and messages on a terminal,
+and JSON when their output goes to another program; `--json` asks for JSON
+anywhere. `--no-input` makes a command fail instead of asking a question, and
+`--project <namespace>/<name>` picks a project other than the one the workspace
+is linked to. The [CLI reference](docs/cli.md) covers output formats, exit
+codes, credentials and each command's JSON.
 
 ## Commands
 
-### `tracel train`
+### `tracel login`, `logout` and `auth`
 
-Run your project locally. This is a thin alias for `cargo run`: every argument
-after `--` is forwarded to your binary, so `tracel train -- <args>` is equivalent
-to `cargo run -- <args>`. stdin/stdout/stderr are inherited and the binary's
-exit code is propagated.
+`tracel login` shows a link and a code, and offers to open the link in your
+browser. Approve the login there and the CLI is logged in for seven days.
 
 ```bash
-# Equivalent to `cargo run`
-tracel train
-
-# Equivalent to `cargo run -- train mnist --epochs 100`
-tracel train -- train mnist --epochs 100
+tracel login
+tracel logout
+tracel auth status    # which credential commands use, and when the login ends
 ```
 
-### `tracel package`
-
-Package your project for deployment on remote compute providers.
+Scripts can log in in two steps, or use an API key from the Console instead:
 
 ```bash
-tracel package
+tracel login --no-wait      # prints the link and the code to approve
+tracel login --complete     # waits for the approval
+TRACEL_API_KEY=... tracel me
+curl -H "Authorization: Bearer $(tracel auth token)" \
+  https://console.tracel.ai/api/v1/user/organizations
 ```
 
-This creates a deployable artifact containing your code, dependencies, and configurations.
-
-### `tracel login`
+### `tracel me`
 
-Authenticate with the Console platform. The CLI prints a link and a code to
-approve in your browser, and the login then lasts seven days.
+Show who you are logged in as.
 
 ```bash
-tracel login
+tracel me
 ```
 
-When `TRACEL_API_KEY` is set, commands use that API key instead of the login.
+### `tracel init` and `unlink`
 
-### `tracel logout`
-
-End the login on the server and forget it locally.
+Link the workspace, the Cargo workspace you run it in, to a project on the
+Tracel Console, creating the project if it doesn't exist. The link is saved in
+`tracel.toml` at the workspace root.
 
 ```bash
-tracel logout
+tracel init
+tracel init --owner my-org --name mnist --yes --allow-dirty
+tracel unlink
 ```
 
-### `tracel auth`
-
-```bash
-# Which credential commands use, the user they act as, and when the login ends
-tracel auth status
-
-# Print an access token of the login for scripts; TRACEL_API_KEY is ignored
-curl -H "Authorization: Bearer $(tracel auth token)" https://console.tracel.ai/api/v1/user/organizations
-```
+`init` needs a git commit, and offers to commit your changes. `--force` links a
+workspace that is already linked to another project.
 
-### `tracel init`
+### `tracel project`
 
-Initialize or reinitialize a Tracel project in the current directory.
+Show the project the workspace is linked to, or list your projects and your
+organizations' projects.
 
 ```bash
-# Interactive initialization
-tracel init
+tracel project
+tracel project list
+tracel project list my-org
 ```
 
-### `tracel unlink`
+### `tracel train`
 
-Unlink the current directory from Tracel project.
+Run the workspace locally with `cargo run`. Arguments after `--` go to your
+program, and its output and exit code are the command's.
 
 ```bash
-tracel unlink
+tracel train -- --epochs 10
 ```
 
-### `tracel me`
+### `tracel package`
 
-Display information about the currently authenticated user.
+Upload a code version of the workspace, the code compute providers run: a
+compiled binary, or the source to build there. A code version is the current
+commit, so `package` offers to commit your changes first.
 
 ```bash
-tracel me
+tracel package
+tracel package --mode binary --target x86_64-unknown-linux-gnu --json
+tracel package --mode source --allow-dirty
 ```
 
-### `tracel project`
+### `tracel experiments`
 
-Display information about the current project.
+Browse the project's experiments by their number, along with their metrics and
+logs. `exp` is short for `experiments`.
 
 ```bash
-tracel project
+tracel experiments list --sort created_at,desc --limit 10
+tracel exp get latest
+tracel exp metrics 42 --metric loss
+tracel exp logs 42 --level warn --level error
+tracel exp logs 42 --follow
 ```
 
-## Project Structure
+### `tracel models`
 
-The Tracel CLI is organized as a Cargo workspace:
+Browse the project's models and their versions, download and upload versions,
+make an experiment's artifact a new version, and point aliases at versions.
+A version is a number such as `7` or `v7`, an alias, or `latest`.
 
-```text
-tracel-cli/
-├── crates/
-│   └── tracel-cli/ 
-└── xtask/                       # Build utilities
+```bash
+tracel models list
+tracel models get my-model --version production
+tracel models versions my-model --all
+tracel models pull my-model --version v7 --directory ./weights
+tracel models push my-model --directory ./weights --auto-create true
+tracel models promote my-model --experiment 42 --artifact weights
+tracel models alias set my-model production 7
 ```
 
-## Development
+### `tracel artifacts`
 
-### Running from source
+List the artifacts of an experiment, and download one by name or id.
 
 ```bash
-cargo run --bin tracel-- --help
+tracel artifacts list 42
+tracel artifacts download 42 weights --directory ./weights
 ```
 
-### Running tests
+### `tracel datasets`
+
+Browse the project's datasets and their published versions.
 
 ```bash
-cargo test
+tracel datasets list
+tracel datasets get images
+tracel datasets versions images
 ```
 
-### Development mode
-
-For testing against a local Console instance:
+## Development
 
 ```bash
-tracel --dev login
+cargo run --bin tracel -- --help
+cargo test
 ```
 
-This connects to `http://localhost:9001` and uses separate development credentials.
-
-## Contribution
+The repository is a Cargo workspace: the CLI is in `crates/tracel-cli`, and
+`xtask` holds the build tasks.
 
-Contributions are welcome! Please feel free to:
+## Contributing
 
-- Report issues or bugs
-- Request new features
-- Submit pull requests
-- Improve documentation
+Issues and pull requests are welcome, whether they report a bug, ask for a
+feature or improve the documentation.
 
 ## License
 
@@ -191,6 +207,6 @@ at your option.
 
 ## Links
 
-- [Console Platform](https://console.tracel.ai/)
+- [Tracel Console](https://console.tracel.ai/)
 - [Tracel SDK](https://github.com/tracel-ai/tracel)
-- [Burn Framework](https://github.com/tracel-ai/burn)
+- [Burn](https://github.com/tracel-ai/burn)

crates/tracel-cli/Cargo.toml

@@ -19,21 +19,25 @@ path = "src/bin/tracel.rs"
 tracel-client.workspace = true
 anyhow.workspace = true
 clap.workspace = true
-colored.workspace = true
 console.workspace = true
 cliclack.workspace = true
-directories.workspace = true
+supports-hyperlinks.workspace = true
+webbrowser.workspace = true
 serde.workspace = true
 serde_json.workspace = true
+chrono.workspace = true
 sha2.workspace = true
 thiserror.workspace = true
 toml_edit.workspace = true
 url.workspace = true
 toml.workspace = true
 gix.workspace = true
-tracing.workspace = true
 cargo_metadata.workspace = true
 ignore.workspace = true
 flate2.workspace = true
 tar.workspace = true
 walkdir.workspace = true
+
+[dev-dependencies]
+rstest.workspace = true
+tempfile.workspace = true

crates/tracel-cli/src/bin/tracel.rs

@@ -1,3 +1,3 @@
 pub fn main() {
-    tracel_cli::cli::cli_main();
+    tracel_cli::cli_main();
 }