npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@vellumai/cli

v0.12.10

Published

CLI tools for vellum-assistant

Readme

@vellumai/cli

CLI tools for provisioning and managing Vellum assistant instances.

Installation

This package is used internally by the vel CLI. You typically don't need to install it directly.

To run it standalone with Bun:

bun run ./src/index.ts <command> [options]

Commands

Lifecycle: ps, sleep, wake

Day-to-day process management for the assistant and gateway.

| Command | Description | | -------------- | -------------------------------------------------------------------------------------- | | vellum ps | List assistants and per-assistant process status (assistant, gateway PIDs and health). | | vellum sleep | Stop assistant and gateway processes. Directory-agnostic — works from anywhere. | | vellum wake | Start the assistant and gateway from the current checkout. |

# Start everything
vellum wake

# Check what's running
vellum ps

# Stop everything
vellum sleep

Note: vellum wake requires a hatched assistant. Run vellum hatch first, or launch the macOS app which handles hatching automatically.

hatch

Provision a new assistant instance and bootstrap the Vellum runtime on it.

vellum hatch [species] [options]

Species

| Species | Description | | ---------- | ------------------------------------------------- | | vellum | Default. Provisions the Vellum assistant runtime. | | openclaw | Provisions the OpenClaw runtime with gateway. |

Options

| Option | Description | | ------------------- | ---------------------------------------------------------------------------------------------------- | | -d | Detached mode. Start the instance in the background without watching startup progress. | | --name <name> | Use a specific instance name instead of an auto-generated one. | | --remote <target> | Where to provision the instance. One of: local, docker, vellum, custom. Defaults to local. |

Remote Targets

  • local -- Starts the local assistant and local gateway. Gateway source resolution order is: repo source tree, then installed @vellumai/vellum-gateway package.
  • docker -- Starts the assistant, gateway, and credential service in Docker containers.
  • vellum -- Hatches an assistant on the Vellum platform.
  • custom -- Recognized but not yet implemented.

Environment Variables

| Variable | Required For | Description | | ------------------- | ------------ | -------------------------------------------------------------------------- | | ANTHROPIC_API_KEY | Optional | Used during setup when no Anthropic API key is already stored or prompted. |

Examples

# Hatch a local assistant (default)
vellum hatch

# Hatch a Docker assistant
vellum hatch --remote docker

# Hatch with a specific instance name
vellum hatch --name my-assistant --remote docker

To self-host on a cloud VM (AWS, GCP, or any other provider), SSH into the machine and run vellum hatch or vellum hatch --remote docker from inside it. The CLI does not provision cloud instances for you.

terminal

Open an interactive shell into a managed assistant container. Useful for debugging, inspecting state, or working alongside the assistant in a shared tmux session.

vellum terminal [name] [options]
vellum terminal attach <session> [name] [options]
vellum terminal list [name] [options]

Only available for managed assistants (those running in a Vellum Cloud container). Local assistants don't have a container to terminal into.

Subcommands

| Subcommand | Description | | ------------------ | ------------------------------------------------------------------ | | (none) | Open an interactive shell session inside the container. | | attach <session> | Attach to an existing tmux session by name inside the container. | | list | List the tmux sessions currently running inside the container. |

Options

| Option | Description | | -------------------- | --------------------------------------------------------------------------------------------------- | | [name] | Positional. Name of the assistant to target. Defaults to the active assistant set via vellum use. | | --assistant <name> | Explicit form of the assistant name. Equivalent to the positional argument. |

If no assistant is named and no active assistant is set, the CLI uses the only managed assistant in the lockfile -- or errors out if there's more than one. Use vellum ps to see your assistants and vellum use <name> to set the active one.

Examples

# Open a shell in the active managed assistant
vellum terminal

# Target a specific assistant by name
vellum terminal my-assistant
vellum terminal --assistant my-assistant

# List running tmux sessions inside the container
vellum terminal list

# Attach to a named tmux session
vellum terminal attach my-session
vellum terminal attach my-session my-assistant

This pairs well with the terminal-sessions skill, which lets the assistant create and manage its own tmux sessions. You can vellum terminal attach into one of those sessions to watch the assistant work in real time -- for example, pairing on a long-running Claude Code run.

retire

Delete a provisioned assistant instance. The cloud provider and connection details are automatically resolved from the saved assistant config (written during hatch).

vellum retire <name>

The CLI looks up the instance by name in the production lockfile (~/.vellum.lock.json) or the env-scoped lockfile under $XDG_CONFIG_HOME/vellum-<env>/lockfile.json for non-production environments, then determines how to retire it based on the saved cloud field:

  • gcp -- Deletes the GCP Compute Engine instance via gcloud compute instances delete.
  • aws -- Terminates the AWS EC2 instance by looking up the instance ID from its Name tag.
  • local -- Stops the local assistant (vellum sleep) and removes the assistant's instance directory (resources.instanceDir in the lockfile; typically ~/.local/share/vellum/assistants/<name>/ for new hatches, or ~/.vellum/ for legacy entries).
  • custom -- SSHs to the remote host to stop the assistant/gateway and remove the remote ~/.vellum directory.

Examples

# Retire an instance (cloud type resolved from config)
vellum retire my-assistant