Add nebi CLI tool

[Adam-D-Lewis]

Darb CLI is the command-line interface for managing reproducible conda environments using OCI registries. It enables users to create, push, pull, and manage environments from the terminal.

Overview

The CLI should support all workflows defined in #8, enabling both standalone usage (darb <command>) and as a pixi extension (pixi darb <command>).

Target Registries

Initial implementation should focus on:

• Docker Hub
• GitHub Container Registry (ghcr.io)
• Quay.io

Users authenticate using the native CLI tools of each registry (e.g., docker login, gh auth login). Darb reads existing credentials from the system.

Commands

Registry Management

# Add a registry to browse/pull from
darb registry add ghcr.io/myorg

# List configured registries
darb registry list

# Remove a registry
darb registry remove ghcr.io/myorg

Environment Operations

# Create a new environment (wraps pixi init + pixi add)
darb env create myenv
darb env create myenv --packages numpy pandas scikit-learn

# List environments
darb env list              # all environments
darb env list --local      # only local
darb env list --remote     # only from subscribed registries

# Show environment details
darb env info myenv

# Delete a local environment
darb env delete myenv

# List versions/tags of a remote environment
darb env versions ghcr.io/myorg/data-science

Push & Pull

# Push environment to registry
darb push                                    # push from current directory
darb push myenv                              # push named environment
darb push myenv --tag v1.0.0                 # push with specific tag
darb push myenv --tag stable                 # semantic tags supported

# Pull environment from registry
darb pull ghcr.io/myorg/data-science         # pull latest
darb pull ghcr.io/myorg/data-science:v1.0.0  # pull specific version
darb pull ghcr.io/myorg/data-science:stable  # pull by tag

Activation (ref: #7)

# Activate environment (conda-like workflow)
darb activate myenv

# Deactivate environment
darb deactivate

# Shell into environment
darb shell myenv

Pixi Extension Support

Darb should be usable as a pixi extension. When installed, users can run:

pixi darb push
pixi darb pull ghcr.io/myorg/data-science
pixi darb registry add ghcr.io/myorg

This is achieved by naming the binary pixi-darb, which pixi automatically discovers as a subcommand.

Note on Upstream Pixi Work

There is ongoing work in pixi to support conda-like named environments natively:

• PR #5277: Adds pixi registry add/list/remove commands for named workspace support

If this lands upstream, Darb may leverage it directly. In the interim, Darb should provide its own activation mechanism to enable the conda-like workflow that data scientists expect (see #7).

@Adam-D-Lewis's WIP PR: #4

[Adam-D-Lewis]

@aktech What do you think of this?

• Instead of darb env, I call it darb repo. This is b/c each pixi.toml is not a single environment. It's a workspace with potentially many envs (run, dev, test, build, etc.). Also the darb name for a (pixi.toml + pixi.lock) is not necessarily the same as the pixi workspace name or pixi env names so I call it "repo" to differentiate, but I'm open to alternative names (e.g. space, bucket, bundle, stack, distro, snapshot, etc.). In a naive implementation, the name of the "darb repo" is the same as the OCI registry repo name e.g. docker.io/myOrg/revenue-project:v1. Where revenue-project is the darb repo name though that is an implementation detail and we might not actually implement it that way.
• Registries have names now which I think makes the cli ux a bit nicer.
• I also got rid of darb activate since it's the same as darb shell and deativate since I think we're okay with the pixi workflow of exiting the subshell.
• I also added a way to pull via digest that would be the recommended way for persistent use of an env (not affected by renaming)

Darb CLI Specification

Command Overview

Command	Description
darb registry add <name> <url>	Add named registry
darb registry list	List registries
darb registry remove <name>	Remove registry
darb registry set-default <name>	Set default registry (makes -r optional in most commands)
darb push <repo>:<tag> [-r <registry>]	Push pixi manifest to registry
darb pull <repo>[:<tag>] [-r <registry>]	Pull repo from registry (default: latest)
darb pull <repo>@<digest> [-r <registry>]	Pull by digest (automation-friendly, immutable)
darb repo list [-r <registry>]	List repos (local or remote)
darb repo list tags <repo> [-r <registry>]	List tags for repo
darb repo info <repo> [-r <registry>]	Show repo details (local or remote)
darb shell <repo> [-r <registry>] -e <env>	Activate env shell (uses pixi shell)
darb login <url>	Login to Darb server
darb logout	Logout from server

Common Flags

Flag	Short	Used In	Description
--registry	-r	push, pull, repo *	Named registry (optional if default set)
--env	-e	shell	Pixi environment name (e.g. pixi shell -e dev)

---

Registry Commands

# Add registries with credentials (depenent on the oci registry type for how to pass credentials in)
darb registry add ds-team ghcr.io/myorg/data-science 
darb registry add infra-team ghcr.io/myorg/infra

# List all registries
darb registry list

# Remove a registry
darb registry remove ds-team

# Set default registry (makes -r optional on other commands)
darb registry set-default ds-team

Push/Pull Commands

# Push with tag
darb push myenv:v1.0.0 -r ds-team

# Pull specific tag
darb pull data-science:v1.0.0 -r ds-team

# Pull latest (default)
darb pull data-science -r ds-team

# Pull by digest (automation-friendly, immutable)
darb pull data-science@sha256:abc123def -r ds-team

Repo Commands

# List local repos
darb repo list

# List remote repos from registry
darb repo list -r ds-team

# List tags for a repo
darb repo list tags data-science -r ds-team

# Create local env
use pixi commands directly

# Delete local env
use pixi commands directly

# Show repo info
darb repo info myenv
darb repo info data-science -r ds-team

# Activate env shell (uses pixi shell)
darb shell myenv
darb shell data-science -r ds-team -e dev

Server Mode (Login)

# Login to Darb server (enables server mode)
darb login https://darb.company.com

# Logout (returns to direct mode)
darb logout

[Adam-D-Lewis]

@aktech I'm assuming that I can implement the CLI just using the darb backend OpenAPI spec. Like the desktop app should include that back-end server, so if this CLI implementation just hits those endpoints, it should be fine, right?

[Adam-D-Lewis]

feedback from @aktech

• change repo to workspace with ws alias
• add local and remote flags for listing ws (see Add --local, --remote flags to nebi ws list #17)
• eventually, put all the neby envs in a centralized location (see Consider Centralized Storage of Nebi Workspaces #16)

[Adam-D-Lewis]

One thing to keep in mind now that we're calling it workspace is that the darb workspace name is not the same as the pixi workspace name.