Metadata-Version: 2.4
Name: infravana-cli
Version: 0.1.1
Summary: Command-line client for InfraVana SmartDeploy
Author: InfraVana
Project-URL: Homepage, https://infravana.com/smartdeploy
Project-URL: Documentation, https://github.com/Infravana/Smart-Deploy-Webpage/tree/main/docs/guides
Project-URL: Source, https://github.com/Infravana/Smart-Deploy-Webpage
Project-URL: Issues, https://github.com/Infravana/Smart-Deploy-Webpage/issues
Keywords: infravana,smartdeploy,llm,simulation,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: PyYAML<7,>=6.0.2

# InfraVana CLI

The InfraVana CLI lets you authenticate with your normal InfraVana account, list your projects, and create experiments from JSON or YAML configuration files.

The CLI uses a short-lived user access token. An API key is not required.

## Choose local or online SmartDeploy

Before using the CLI, choose where your projects and experiments should be created.

For your local website and local database:

```bash
export INFRAVANA_API_URL="http://127.0.0.1:8000"
infravana auth login
```

For the online SmartDeploy website and production database:

```bash
export INFRAVANA_API_URL="https://infravana.com/smartdeploy"
infravana auth login
```

Check the currently selected environment before creating anything:

```bash
echo "$INFRAVANA_API_URL"
infravana auth status
```

Local and online SmartDeploy use different databases. Sign in again whenever you switch between them.

## Quick start

Install the public package from PyPI:

```bash
python3 -m pip install --user infravana-cli
```

Upgrade an existing installation with:

```bash
python3 -m pip install --user --upgrade infravana-cli
```

Verify that the command is available:

```bash
infravana --help
```

After installation, `infravana` works from any directory. Sign in to SmartDeploy:

```bash
infravana auth login
```

The production URL `https://infravana.com/smartdeploy` is the default. For local development only, set:

```bash
export INFRAVANA_API_URL="http://127.0.0.1:8000"
```

Enter your InfraVana email or username and password when prompted. The password is hidden and is never saved. Successful login stores a 12-hour access token in:

```text
~/.config/infravana/credentials.json
```

The credentials file is readable only by your operating-system user. All later CLI commands automatically use the saved access token.

## Complete workflow

The following example signs in, creates a project, creates a group containing that project, generates an editable experiment file, and submits it:

```bash
# 1. Sign in and save the 12-hour access token.
infravana auth login

# 2. Create a project and copy the project ID printed by the command.
infravana projects create \
  --name "Simulator imports" \
  --description "Experiments submitted through the CLI"

# 3. Create a group containing the new project.
infravana groups create \
  --name "Simulation team" \
  --project-id PROJ-SIMULATOR-IMPORTS

# 4. Generate an editable experiment file in the current directory.
infravana experiments init my-experiment.json \
  --project-id PROJ-SIMULATOR-IMPORTS \
  --name "Imported simulator run"

# 5. Edit the model, hardware, workload, and serving configuration.
nano my-experiment.json

# 6. Validate the file without creating an experiment.
infravana experiments create \
  --file my-experiment.json \
  --dry-run

# 7. Create and queue the experiment.
infravana experiments create \
  --file my-experiment.json
```

Replace `PROJ-SIMULATOR-IMPORTS` with the exact project ID printed in step 2.

## Command summary

| Task | Command |
| --- | --- |
| Sign in | `infravana auth login` |
| Show current account | `infravana auth status` |
| Sign out | `infravana auth logout` |
| List projects | `infravana projects list` |
| Create a project | `infravana projects create --name "Project name"` |
| List groups | `infravana groups list` |
| Create a group | `infravana groups create --name "Group name"` |
| Add projects to a group | `infravana groups add-projects --group-id 7 --project-id PROJ-ID` |
| Create an editable experiment template | `infravana experiments init my-experiment.json` |
| Validate an experiment | `infravana experiments create --file FILE --project-id PROJ-ID --name "Name" --dry-run` |
| Create an experiment | `infravana experiments create --file FILE --project-id PROJ-ID --name "Name"` |

## Global options

Global options must appear before the resource name:

```bash
infravana --api-url URL --access-token TOKEN projects list
```

- `--api-url URL` overrides the default SmartDeploy API URL for one command.
- `--access-token TOKEN` overrides the saved access token for one command. Prefer the saved login or `INFRAVANA_ACCESS_TOKEN` to avoid exposing a token in shell history.
- `-h` or `--help` displays help for any command, such as `infravana experiments create --help`.

## Roles and permissions

The CLI does not bypass InfraVana permissions. Every request is authorized as the user represented by the saved access token.

- **Guest and Viewer:** read-only; cannot create projects or experiments.
- **Researcher:** can create projects owned by their account and create experiments in projects where they are the owner, Contributor, or Manager.
- **Contributor:** can create experiments in the assigned project but cannot manage the project itself.
- **Project Manager:** can manage and create experiments in the assigned project.
- **System Admin and Owner:** have broader administrative visibility according to the platform role policy.

Private projects belonging to unrelated users are not listed and cannot be targeted by changing `--project-id`. Projects or runs that are public or explicitly shared with you can still appear because access was intentionally granted.

## Authentication commands

Check your current login:

```bash
infravana auth status
```

Sign in and optionally open the web dashboard:

```bash
infravana auth login --open-browser
```

Provide the email address or username without waiting for the identifier prompt:

```bash
infravana auth login --identifier user@example.com
```

The password is still requested securely. After login, later commands use the saved access token rather than asking for the username and password again.

Sign out, revoke the token, and remove the saved credentials:

```bash
infravana auth logout
```

## Find a project ID

List the projects available to your account:

```bash
infravana projects list
```

Example output:

```text
Project ID             Name
PROJ-LLM-SERVE         LLM Serving
```

For JSON output:

```bash
infravana projects list --json
```

## Create a project

Create a project using the saved access token:

```bash
infravana projects create \
  --name "My new project" \
  --description "Experiments imported from my simulator"
```

InfraVana generates the project ID and prints it after creation. To request a specific ID instead:

```bash
infravana projects create \
  --name "My new project" \
  --description "Experiments imported from my simulator" \
  --project-id PROJ-MY-SIMULATOR
```

The ID must be unique. Use the returned project ID with `experiments create`.

## Create and manage groups

Create an empty collaboration group:

```bash
infravana groups create --name "Performance team"
```

Create a group and add one or more projects immediately. Repeat `--project-id` for multiple projects:

```bash
infravana groups create \
  --name "Performance team" \
  --project-id PROJ-LLM-SERVE \
  --project-id PROJ-COLLECTIVES
```

You can also add members by their complete InfraVana username:

```bash
infravana groups create \
  --name "Performance team" \
  --member-username member@example.com \
  --project-id PROJ-LLM-SERVE
```

List groups and their project IDs:

```bash
infravana groups list
```

Add `--json` to project, group, or experiment API commands when a script needs the complete machine-readable response.

Add projects to an existing group without removing its current projects or runs:

```bash
infravana groups add-projects \
  --group-id 7 \
  --project-id PROJ-LLM-SERVE \
  --project-id PROJ-COLLECTIVES
```

The backend accepts only projects owned by the authenticated user. Group members may add their own projects, but cannot add another user's private project. Guests and Viewers cannot create groups or share projects.

## Create an experiment from a simulator file

The CLI accepts simulator-generated files ending in:

- `.json`
- `.yaml`
- `.yml`

The filename can be anything. For example:

```bash
infravana experiments create \
  --file /path/to/simulator-output.json \
  --project-id PROJ-LLM-SERVE \
  --name "My simulator experiment"
```

YAML support is included when the CLI is installed. Submit YAML in the same way:

```bash
infravana experiments create \
  --file /path/to/simulator-output.yaml \
  --project-id PROJ-LLM-SERVE \
  --name "My YAML simulator experiment"
```

For a raw simulator file, the CLI uses the entire top-level JSON/YAML object as the experiment `config`. It adds `project_id` and `name` from the command-line options.

The simulator configuration must contain the fields required by the InfraVana API:

- `model`
- `hardware`
- `parallelism`
- `workload`
- `serving`

## Validate before submitting

Use `--dry-run` to parse and print the final request without creating an experiment:

```bash
infravana experiments create \
  --file /path/to/simulator-output.json \
  --project-id PROJ-LLM-SERVE \
  --name "My simulator experiment" \
  --dry-run
```

## Use the InfraVana template

Any user with the installed CLI can generate and edit an experiment template from any directory:

```bash
infravana experiments init my-experiment.json
nano my-experiment.json
```

The project and experiment name can be filled in immediately:

```bash
infravana experiments init my-experiment.json \
  --project-id PROJ-LLM-SERVE \
  --name "My experiment"
```

The command refuses to overwrite an existing file. Add `--force` only when you intentionally want to replace it.

`experiments init` creates JSON templates. It does not require authentication because it only writes a local file. Authentication is required when `experiments create` submits that file to InfraVana.

Because this template already contains `project_id`, `name`, and `config`, submit it with:

```bash
infravana experiments create --file my-experiment.json
```

## Successful result

```text
Experiment created and queued.
Experiment: My simulator experiment
Experiment ID: EXP-CE0DF1FE9D34
Status: queued
Run IDs: RUN-75C8E2E566
Idempotency key: cli-54b78c6d-a499-4563-9bf7-2a50ff405cc1
```

Use `--json` to print the complete API response:

```bash
infravana experiments create \
  --file my-experiment.json \
  --json
```

## Retry without creating a duplicate

If a request is interrupted, retry with the same idempotency key printed by the original command:

```bash
infravana experiments create \
  --file my-experiment.json \
  --idempotency-key "ORIGINAL_IDEMPOTENCY_KEY"
```

## Optional token override

For automation, an existing access token can be supplied through the environment:

```bash
export INFRAVANA_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
infravana projects list
```

Do not commit or share access tokens. Interactive users should prefer `auth login`, which avoids putting the token in shell history.

## Troubleshooting

### You are not signed in

```bash
infravana auth login
```

### The API cannot be reached

Confirm Django is running, then set:

```bash
export INFRAVANA_API_URL="http://127.0.0.1:8000"
```

### The `infravana` command is not found

Upgrade or reinstall the CLI from PyPI using the command in [Quick start](#quick-start). If installation succeeds but the command is still missing, ensure your Python user scripts directory is included in `PATH`.

### The project cannot be found

Run `infravana projects list` and use a project ID available to your account.

### The simulator configuration is invalid

Run the command with `--dry-run`, then confirm the raw configuration contains all fields required by the simulation API.

For a longer walkthrough, see [`docs/guides/CLI.md`](../docs/guides/CLI.md).
