updose

v1.1.0

Published

23 days ago

AI coding tool boilerplate marketplace

0High
0Medium
0Low

alchemist85k

ai boilerplate claude codex gemini cli

updose

Search, install, and share boilerplates for AI coding tools.

Manage configurations for Claude Code, Codex, and Gemini CLI through GitHub repositories.

Requires Node.js 18 or later.

npx updose <command>

updose

Quick Start

# Search for boilerplates in the marketplace
npx updose search react

# Install a boilerplate from a GitHub repository
npx updose add owner/repo-name

# Install from a subdirectory within a monorepo
npx updose add owner/repo-name/nextjs

Commands

`updose add <repo>`

Install a boilerplate from a GitHub repository into your project.

The <repo> argument accepts two formats:

owner/repo — installs from the repository root (standard boilerplate)
owner/repo/dir — installs from a subdirectory within the repository (monorepo boilerplate). The dir can be nested (e.g., owner/repo/templates/v2).

npx updose add owner/repo-name                  # Install from repository root
npx updose add owner/repo-name/nextjs            # Install from "nextjs" subdirectory
npx updose add owner/repo-name/templates/v2      # Install from nested subdirectory
npx updose add owner/repo-name -y                # Skip all prompts
npx updose add owner/repo-name/nextjs --dry-run  # Preview monorepo install

What happens when you run add:

Parses the <repo> argument to determine the repository (owner/repo) and optional subdirectory
Fetches the boilerplate's updose.json manifest from the repository root or the specified subdirectory
If the boilerplate supports multiple targets (e.g., both Claude and Gemini), prompts you to choose which targets to install. With -y, all targets are installed automatically.
Downloads the file tree from the repository and filters files for the selected target(s). When a subdirectory is specified, only files under that subdirectory are considered.
Installs each file into your project. If a file already exists, the prompt depends on the file type:
- Main docs (CLAUDE.md, AGENTS.md, GEMINI.md): Append / Overwrite / Skip
- Other files (rules, commands, agents, etc.): Overwrite / Skip
If a skills.json file exists in the boilerplate (or its subdirectory), installs each declared skill via skills.sh. Skills are installed for the selected targets (-a), copied into the project (--copy), and auto-confirmed (-y)

Example — after installing a Claude boilerplate:

my-project/
├── CLAUDE.md                          ← main instructions (project root)
├── .claude/
│   ├── rules/
│   │   ├── code-style.md
│   │   └── testing.md
│   ├── commands/
│   │   ├── review.md
│   │   └── test.md
│   ├── agents/
│   │   └── reviewer.md
│   └── skills/
│       └── react-guide/
│           └── SKILL.md

See the full example in examples/after-install-claude/. Also available: examples/after-install-codex/ and examples/after-install-gemini/.

`updose search [query]`

Search the marketplace for boilerplates. The query is optional — you can search by keyword, filter by options, or combine both.

# Search by keyword
npx updose search react
npx updose search "web framework"

# Filter by target, tag, or author
npx updose search --target claude       # Only show boilerplates that support Claude
npx updose search --tag typescript      # Filter by tag
npx updose search --author james        # Filter by author

# Combine keyword with filters
npx updose search react --target claude              # React boilerplates for Claude
npx updose search react --author james               # React boilerplates by james
npx updose search react --target gemini --tag web    # React + Gemini + web tag

# Filter-only search (no keyword)
npx updose search --author james                      # All boilerplates by james
npx updose search --author james --target claude      # james's Claude boilerplates
npx updose search --tag typescript --target codex     # TypeScript boilerplates for Codex

Running npx updose search with no arguments returns popular boilerplates.

Results display the boilerplate name, version, author, description, download count, supported targets, and tags.

`updose init`

Scaffold a new boilerplate repository with the correct directory structure.

mkdir my-boilerplate && cd my-boilerplate
npx updose init

To scaffold inside a subdirectory (for monorepo setups), use the --dir option:

npx updose init --dir nextjs          # Creates boilerplate in the "nextjs" subdirectory
npx updose init --dir templates/v2    # Nested subdirectory is also supported

What happens when you run init:

Prompts you for boilerplate configuration (see below)
Generates updose.json, skills.json, README.md, and target directories
If a file already exists, asks whether to Overwrite or Skip
Shows next steps for publishing

When --dir is used, all generated files are placed inside the specified subdirectory instead of the repository root.

Interactive prompts:

Generated files:

Every scaffold includes these common files:

Plus target-specific directories based on your selection:

Example — scaffolding with all targets selected (no --dir):

my-boilerplate/
├── updose.json
├── skills.json
├── README.md
├── claude/
│   ├── CLAUDE.md
│   ├── rules/
│   ├── agents/
│   └── skills/
├── codex/
│   └── AGENTS.md
└── gemini/
    ├── GEMINI.md
    └── skills/

Example — scaffolding with --dir nextjs:

my-monorepo/
├── nextjs/                  ← created by --dir
│   ├── updose.json
│   ├── skills.json
│   ├── README.md
│   ├── claude/
│   │   ├── CLAUDE.md
│   │   ├── rules/
│   │   ├── agents/
│   │   └── skills/
│   ├── codex/
│   │   └── AGENTS.md
│   └── gemini/
│       ├── GEMINI.md
│       └── skills/
├── remix/                   ← another boilerplate in the same repo
│   └── ...
└── README.md                ← repo-level README (not managed by updose)

After scaffolding, follow the next steps printed by the command:

Edit your boilerplate files in each target directory
Push to GitHub
Publish with npx updose publish (or npx updose publish --dir nextjs for monorepo)
Others can install with npx updose add <author>/<name> (or npx updose add <author>/<repo>/nextjs for monorepo)

`updose publish`

Publish your boilerplate to the marketplace so others can find and install it. The repository must be public — private repositories cannot be published because users need to clone the repository when installing boilerplates.

npx updose publish                   # Publish from repository root
npx updose publish --dir nextjs      # Publish from a subdirectory (monorepo)

What happens when you run publish:

Reads and parses updose.json from the current directory (or the subdirectory specified by --dir). If the file is missing, shows an error and suggests running updose init first.
Validates the manifest structure (name, author, version, targets are required)
Detects the GitHub repository by running git remote get-url origin. Supports both HTTPS (https://github.com/owner/repo.git) and SSH ([email protected]:owner/repo.git) formats.
Validates that author and name in updose.json match the expected name:
- Without --dir: name must match the repository name (e.g., react-starter)
- With --dir: name must match <repo>/<dir> (e.g., my-monorepo/nextjs)
Authenticates via GitHub — if no valid token exists, automatically runs the login flow (see below)
Verifies the repository actually exists on GitHub. If the repo has not been pushed yet, shows an error and exits.
Displays a publication summary for review:

Publishing:
  Name:        react-starter
  Version:     1.0.0
  Repository:  example-user/react-starter
  Targets:     claude, gemini
  Tags:        react, typescript, web

When --dir is used, the summary also includes a Directory field:

Publishing:
  Name:        my-monorepo/nextjs
  Version:     1.0.0
  Repository:  example-user/my-monorepo
  Directory:   nextjs
  Targets:     claude
  Tags:        react, nextjs

Asks for confirmation: "Publish to registry?" (defaults to yes). If declined, displays "Publish cancelled." and exits.
Registers the boilerplate in the marketplace registry
On success, displays the install command:
- Without --dir: Users can now install with: npx updose add owner/repo
- With --dir: Users can now install with: npx updose add owner/repo/dir

Prerequisites:

A valid updose.json in the current directory or specified subdirectory (run updose init to create one)
A public GitHub repository — private repositories cannot be published
A GitHub remote (origin) configured and pushed to GitHub
GitHub authentication (handled automatically if not already logged in)

`updose login`

Authenticate with GitHub using the Device Flow.

npx updose login

What happens when you run login:

Checks for an existing token stored at ~/.updose/auth.json
If a token is found, verifies it by calling the GitHub API
- If valid, displays "Already logged in as {username}" and exits immediately
- If invalid/expired, proceeds to re-authenticate
Initiates the GitHub Device Flow and displays instructions:

To authenticate with GitHub:

  1. Open https://github.com/login/device
  2. Enter code: ABCD-1234

Polls GitHub for authorization until you enter the code on the website
On success, fetches your GitHub username and stores the credentials at ~/.updose/auth.json (file permissions: owner read/write only)

Stored credentials (~/.updose/auth.json):

{
  "github_token": "gho_xxxxxxxxxxxx",
  "github_username": "your-username"
}

The token is requested with public_repo scope, which grants read/write access to public repositories only.

`updose logout`

Remove stored GitHub credentials.

npx updose logout

What happens when you run logout:

Reads the stored auth data from ~/.updose/auth.json
If no auth file is found, displays "Not currently logged in." and exits
If auth exists, deletes ~/.updose/auth.json and displays "Logged out from {username}."

Supported Targets

updose supports three AI coding tool targets:

Where Files Get Installed

When you run updose add, files from the boilerplate's target directory are mapped to your project:

Main docs (CLAUDE.md, AGENTS.md, GEMINI.md) are always placed at the project root. All other files go into the target's config directory.

File Conflict Resolution

When a file already exists in your project, updose asks how to handle it:

Append — adds the new content to the end of the existing file, separated by ---
Overwrite — replaces the file entirely
Skip — leaves the existing file untouched

Creating a Boilerplate

Boilerplate Directory Structure

A boilerplate repository contains a updose.json manifest, an optional skills.json, and one directory per supported target.

my-boilerplate/
├── updose.json              ← required manifest
├── skills.json              ← optional skill dependencies
├── README.md
├── claude/                  ← Claude target files
│   ├── CLAUDE.md
│   ├── rules/
│   │   ├── code-style.md
│   │   └── testing.md
│   ├── commands/
│   │   ├── review.md
│   │   └── test.md
│   ├── agents/
│   │   └── reviewer.md
│   └── skills/
│       └── react-guide/
│           └── SKILL.md
├── codex/                   ← Codex target files
│   ├── AGENTS.md
│   └── .agents/
│       └── skills/
│           └── react-guide/
│               └── SKILL.md
└── gemini/                  ← Gemini target files
    ├── GEMINI.md
    ├── commands/
    │   ├── review.toml
    │   └── test.toml
    └── skills/
        └── react-guide/
            └── SKILL.md

See complete examples in:

examples/boilerplate-claude/ — single-target (Claude)
examples/boilerplate-codex/ — single-target (Codex)
examples/boilerplate-gemini/ — single-target (Gemini)
examples/boilerplate-multi-target/ — multi-target (all three)

`updose.json` Reference

The manifest file that describes your boilerplate.

{
  "name": "react-starter",
  "author": "example-user",
  "version": "1.0.0",
  "description": "React + TypeScript boilerplate for AI coding tools",
  "targets": ["claude", "gemini"],
  "tags": ["react", "typescript", "web"]
}

`skills.json` Reference

An optional file that declares external skill dependencies. When a user installs your boilerplate, these skills are automatically installed via skills.sh.

Each entry in the skills array is a command string (e.g., npx skills add <repo> --skill <name>). During installation, updose automatically appends the following flags:

-a <agents> — installs for the selected targets (e.g., -a claude-code codex gemini-cli)
--copy — copies skill files into the project instead of symlinking
-y — skips confirmation prompts

{
  "skills": [
    "npx skills add https://github.com/intellectronica/agent-skills --skill context7",
    "npx skills add https://github.com/microsoft/playwright-cli --skill playwright-cli"
  ]
}

For example, if a user selects Claude and Gemini as targets, the first command above becomes:

npx skills add https://github.com/intellectronica/agent-skills --skill context7 -a claude-code gemini-cli --copy -y

Skills are installed into the target's skills directory (e.g., .claude/skills/, .gemini/skills/).

Example: Single-Target Boilerplate (Claude)

From examples/boilerplate-claude/:

updose.json

{
  "name": "react-starter",
  "author": "example-user",
  "version": "1.0.0",
  "description": "React + TypeScript boilerplate for Claude Code",
  "targets": ["claude"],
  "tags": ["react", "typescript", "web"]
}

Directory structure:

boilerplate-claude/
├── updose.json
├── skills.json
└── claude/
    ├── CLAUDE.md              ← main instructions (stack, conventions, etc.)
    ├── rules/
    │   ├── code-style.md      ← coding style rules
    │   └── testing.md         ← testing conventions
    ├── commands/
    │   ├── review.md          ← /review slash command
    │   └── test.md            ← /test slash command
    ├── agents/
    │   └── reviewer.md        ← automated reviewer agent
    └── skills/
        └── react-guide/
            └── SKILL.md       ← React best practices skill

When a user runs npx updose add example-user/react-starter, the result looks like examples/after-install-claude/.

Example: Multi-Target Boilerplate

From examples/boilerplate-multi-target/:

A boilerplate can support multiple targets at once. Each target has its own directory with target-specific configurations.

updose.json

{
  "name": "multi-target-starter",
  "author": "example-user",
  "version": "1.0.0",
  "description": "Starter boilerplate for Claude, Codex, and Gemini",
  "targets": ["claude", "codex", "gemini"],
  "tags": ["starter", "multi-target"]
}

Directory structure:

boilerplate-multi-target/
├── updose.json
├── skills.json
├── claude/
│   └── CLAUDE.md
├── codex/
│   └── AGENTS.md
└── gemini/
    └── GEMINI.md

When a user installs a multi-target boilerplate, they are prompted to choose which targets to install. With -y, all targets are installed automatically.

Monorepo Support

A single GitHub repository can contain multiple boilerplates, each in its own subdirectory. This is useful when you want to publish several related boilerplates (e.g., framework-specific starters) from one repo.

How it works:

Each subdirectory is an independent boilerplate with its own updose.json, skills.json, and target directories
The name field in updose.json must be <repo>/<dir> (e.g., my-starters/nextjs)
Users install with npx updose add owner/repo/dir instead of npx updose add owner/repo

Monorepo directory structure:

my-starters/                         ← GitHub repository root
├── README.md                        ← repo-level README (not managed by updose)
├── nextjs/                          ← boilerplate for Next.js
│   ├── updose.json                  ← name: "my-starters/nextjs"
│   ├── skills.json
│   ├── claude/
│   │   ├── CLAUDE.md
│   │   └── rules/
│   │       └── nextjs-conventions.md
│   └── gemini/
│       └── GEMINI.md
├── remix/                           ← boilerplate for Remix
│   ├── updose.json                  ← name: "my-starters/remix"
│   ├── skills.json
│   └── claude/
│       ├── CLAUDE.md
│       └── rules/
│           └── remix-conventions.md
└── sveltekit/                       ← boilerplate for SvelteKit
    ├── updose.json                  ← name: "my-starters/sveltekit"
    ├── skills.json
    └── claude/
        └── CLAUDE.md

updose.json for a monorepo boilerplate (nextjs/updose.json):

{
  "name": "my-starters/nextjs",
  "author": "example-user",
  "version": "1.0.0",
  "description": "Next.js boilerplate for Claude and Gemini",
  "targets": ["claude", "gemini"],
  "tags": ["nextjs", "react", "web"]
}

Note: The name field uses the format <repo>/<dir> (e.g., my-starters/nextjs), not just the directory name.

Workflow for creating a monorepo boilerplate:

# 1. Scaffold each boilerplate in its own subdirectory
npx updose init --dir nextjs
npx updose init --dir remix
npx updose init --dir sveltekit

# 2. Edit each boilerplate's files
# (edit nextjs/claude/CLAUDE.md, remix/claude/CLAUDE.md, etc.)

# 3. Push to GitHub
git add . && git commit -m "Add boilerplates" && git push

# 4. Publish each boilerplate separately
npx updose publish --dir nextjs
npx updose publish --dir remix
npx updose publish --dir sveltekit

Users install each boilerplate independently:

npx updose add example-user/my-starters/nextjs
npx updose add example-user/my-starters/remix

Publishing

To share your boilerplate with others through the marketplace:

Scaffold with npx updose init (or npx updose init --dir <dir> for monorepo)
Add your content (rules, commands, agents, skills, etc.)
Push to a GitHub repository
Run npx updose publish (or npx updose publish --dir <dir> for monorepo)

After publishing, anyone can install your boilerplate:

# Standard boilerplate
npx updose add your-username/my-boilerplate

# Monorepo boilerplate
npx updose add your-username/my-monorepo/nextjs

Privacy Policy

updose uses GitHub OAuth solely to identify authors when publishing boilerplates.

What we collect:

GitHub username (via OAuth)
Boilerplate metadata when publishing (name, version, targets, tags, description)

What we store locally:

GitHub token and username at ~/.updose/auth.json (never sent to updose servers)

What we don't do:

Sell or share personal information with third parties

Third-party services: Supabase (database), Vercel (hosting)

To request data deletion, contact email.

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

updose

Table of Contents

Quick Start

Commands

updose add <repo>

updose search [query]

updose init

updose publish

updose login

updose logout

Supported Targets

Where Files Get Installed

File Conflict Resolution

Creating a Boilerplate

Boilerplate Directory Structure

updose.json Reference

skills.json Reference

Example: Single-Target Boilerplate (Claude)

Example: Multi-Target Boilerplate

Monorepo Support

Publishing

Privacy Policy

License

Sponsors

`updose add <repo>`

`updose search [query]`

`updose init`

`updose publish`

`updose login`

`updose logout`

`updose.json` Reference

`skills.json` Reference