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. It is published publicly as infravana-cli on PyPI.

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:

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

For the online SmartDeploy website and production database:

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

Check the currently selected environment before creating anything:

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:

python3 -m pip install infravana-cli

Upgrade an existing installation with:

python3 -m pip install --upgrade infravana-cli

Verify that the command is available:

infravana --help

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

infravana auth login

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

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:

~/.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:

# 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

Global options

Global options must appear before the resource name:

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:

infravana auth status

Sign in and optionally open the web dashboard:

infravana auth login --open-browser

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

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:

infravana auth logout

Find a project ID

List the projects available to your account:

infravana projects list

Example output:

Project ID             Name
PROJ-LLM-SERVE         LLM Serving

For JSON output:

infravana projects list --json

Create a project

Create a project using the saved access token:

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:

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:

infravana groups create --name "Performance team"

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

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:

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

List groups and their project IDs:

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:

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:

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:

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:

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:

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

The project and experiment name can be filled in immediately:

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:

infravana experiments create --file my-experiment.json

Successful result

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:

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:

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:

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

infravana auth login

The API cannot be reached

Confirm Django is running, then set:

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. 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.