vrctools

🎭 CLI tool for managing VRChat via the API.

Installation

Docker (Recommended for Isolated Usage)

Pull the latest image from GitHub Container Registry:

docker pull ghcr.io/zuedev/vrctools:latest

Run with a volume mount to persist authentication data:

docker run -it --rm \
  -v vrchat-data:/data \
  ghcr.io/zuedev/vrctools:latest avatars

Or using a local directory:

docker run -it --rm \
  -v $(pwd)/data:/data \
  ghcr.io/zuedev/vrctools:latest avatars

Docker Usage Examples:

# List all avatars
docker run -it --rm -v vrchat-data:/data ghcr.io/zuedev/vrctools:latest avatars

# Get current avatar
docker run -it --rm -v vrchat-data:/data ghcr.io/zuedev/vrctools:latest avatars current

# Delete avatars interactively
docker run -it --rm -v vrchat-data:/data ghcr.io/zuedev/vrctools:latest avatars delete

Global Installation (Recommended)

Install globally to use the vrctools command anywhere:

npm install -g vrctools

Or from GitHub Packages:

npm install -g @zuedev/vrctools --registry=https://npm.pkg.github.com

Local Development

npm install

Running Tests

npm test

For more information about testing, see TESTING.md.

Usage

Authentication

On first run, you'll be prompted to enter your VRChat credentials. These are stored locally in data.json.

Commands

Note: If installed globally, use vrctools instead of npm start.

List all avatars

vrctools avatars
# or for local development:
npm start avatars

Fetches and displays all your avatars (both public and private) with pagination support.

Get current avatar

vrctools avatars current
# or for local development:
npm start avatars current

Displays information about your currently equipped avatar.

Delete avatars interactively

vrctools avatars delete
# or for local development:
npm start avatars delete

Cycles through all your avatars. Press "D" to delete the current avatar, or press Enter to skip.