Oxide

Oxide is a Rust CLI for scaffolding JavaScript and TypeScript projects from remote Oxide templates and extending them with project addons.

It supports:

• creating a new project from a template
• checking cached templates and addons for updates before use
• authenticating against the Oxide service
• publishing GitHub repositories as Oxide templates
• installing cached addons and running addon commands inside a project
• upgrading the CLI from GitHub Releases with oxide upgrade
• notifying you when a newer Oxide version is available

Official website

The official Oxide website is oxide-cli.vercel.app.

Use it as the main guide for learning and using Oxide:

• Docs cover installation, authentication, templates, addons, publishing, and reference material.
• Templates lists available project starters.
• Addons lists reusable workflow addons.

This README keeps a quick CLI reference for the repository and package users. The website contains the full, up-to-date usage guide.

Installation

Quick install

Linux and macOS:

curl -sSL https://raw.githubusercontent.com/oxide-cli/oxide/main/install.sh | bash

Windows PowerShell:

irm https://raw.githubusercontent.com/oxide-cli/oxide/main/install.ps1 | iex

Unix installers place the oxide binary in ~/.local/bin. Cargo installs it in ~/.cargo/bin. Make sure the relevant directory is in your PATH.

Install with npm

npm install -g @oxide-cli/oxide

The npm package downloads the matching prebuilt Oxide binary during postinstall.

Install with cargo

cargo install oxide-cli

Manual install from GitHub Releases

Download the latest release artifact for your platform:

• Linux x86_64
• Linux ARM64
• macOS Apple Silicon
• Windows x86_64

Getting started

Most remote operations require authentication first:

oxide login

Create a new project from a template:

oxide new my-app react-vite-ts

Oxide checks whether the cached template is current before generating the project. If a newer template version exists, it updates the local cache first.

Command overview

Top-level commands:

oxide new <NAME> <TEMPLATE_NAME>
oxide template <COMMAND>
oxide login
oxide logout
oxide account
oxide addon <COMMAND>
oxide upgrade
oxide completions <SHELL>
oxide use <ADDON_ID> <COMMAND>

Template management:

oxide template install <TEMPLATE_NAME>
oxide template list
oxide template remove <TEMPLATE_NAME>
oxide template publish <GITHUB_REPOSITORY_URL>
oxide template update <GITHUB_REPOSITORY_URL>

Addon management:

oxide addon install <ADDON_ID>
oxide addon list
oxide addon remove <ADDON_ID>
oxide addon publish <GITHUB_REPOSITORY_URL>
oxide addon update <GITHUB_REPOSITORY_URL>

Addon execution:

oxide use <ADDON_ID> <COMMAND>

Example:

oxide addon install drizzle
cd my-app
oxide use drizzle init

Upgrade Oxide itself:

oxide upgrade

Install shell completions:

oxide completions zsh

Supported shells are bash, zsh, fish, and powershell.

Aliases:

• oxide n ... for oxide new ...
• oxide t ... for oxide template ...
• oxide a ... for oxide addon ...
• oxide in for oxide login
• oxide out for oxide logout

Common workflows

Install or refresh a template in the local cache:

oxide template install react-vite-ts

When you run oxide new, Oxide also refreshes the template cache automatically if a newer version is available.

List cached templates:

oxide template list

Remove a cached template:

oxide template remove react-vite-ts

Show the authenticated account:

oxide account

Publish a GitHub repository as a template:

oxide template publish https://github.com/owner/repo

Update a published template:

oxide template update https://github.com/owner/repo

Install an addon:

oxide addon install drizzle

Run an installed addon command:

oxide use drizzle init

When you run an addon command such as oxide use drizzle init, Oxide checks for a newer cached addon version first. If the add-on updated and the command is marked once: true, Oxide prompts you to re-run it.

List installed addons:

oxide addon list

Remove a cached addon:

oxide addon remove drizzle

Publish a GitHub repository as an addon:

oxide addon publish https://github.com/owner/repo

Update a published addon:

oxide addon update https://github.com/owner/repo

Upgrade the CLI to the latest release:

oxide upgrade

After most commands, Oxide performs a background version check and prints a short upgrade notice when a newer CLI release is available.

Install shell completions:

oxide completions zsh

Supported shells are bash, zsh, fish, and powershell.

Local data and generated files

Oxide stores local state under ~/.oxide/:

• cached templates in ~/.oxide/cache/templates
• cached addons in ~/.oxide/cache/addons
• template cache index in ~/.oxide/cache/templates/oxide-templates.json
• addon cache index in ~/.oxide/cache/addons/oxide-addons.json
• CLI version-check cache in ~/.oxide/version_check.json
• authentication data in ~/.oxide/auth.json

When addon commands run inside a project, Oxide records execution state in oxide.lock in the project root, including the add-on version used for each executed command.

Templates

Published templates are expected to include an oxide.template.json manifest in the template root. Oxide uses that manifest to track template metadata such as template name, version, and source repository.

Template files ending with .tera are rendered during project generation and written without the .tera suffix.

Available template variables:

• project_name
• project_name_kebab
• project_name_snake

Addons

Installed addons are expected to include an oxide.addon.json manifest. Oxide uses addon manifests to define:

• user inputs
• project detection rules
• command variants
• file modification steps such as create, copy, inject, replace, append, delete, rename, and move

License

Licensed under either of these:

• MIT license (LICENSE-MIT)
• Apache License 2.0 (LICENSE-Apache)