Docs

Introduction

Cealshell is a package manager for Roblox Studio. It installs Luau packages straight into your place — no external tooling, no build step, no leaving Studio.

There's no central registry to publish through. Cealshell works as a thin proxy over Git hosts: point it at a public repository that ships a Roblox model (.rbxm or .rbxmx), and it resolves the reference, fetches the model, and drops it into your project. GitHub and Codeberg are supported out of the box.

Getting started

Cealshell is a Studio plugin. Once it's installed, you drive it entirely from the Studio command bar — every command is prefixed with --c:

The leading --cmakes the line a Lua comment, so the command bar never throws. The plugin reads the echoed line back from the log and runs the command. There's nothing else to open — just type and go.

Run --c help for the full command list, or --c manual <command> for details on any single one.

Installing packages

Use install (aliases add, i) to add one or more packages. A package is referenced as author:repo— a public repository on the remote's proxy:

Packages install into ServerStorage by default. Pass -s / --shared to install into ReplicatedStorage instead, so the package is reachable from the client:

Package references

Every reference points at a repository on a Git host. The full grammar is [remote/][provider/]owner:repo[@version], but only owner:repo is required — everything else has a default:

• owner:repo — e.g. janisfox:marble. This is the canonical form.
• @version — e.g. janisfox:marble@1.0.0. Defaults to latest when omitted.
• provider/ — e.g. codeberg/janisfox:marble. Defaults to GitHub when omitted.
• remote/ — a one-off remote override, e.g. cshl.xlch.dev/janisfox:marble. Defaults to your configured remote.

There's no central catalogue and nothing to register — every reference is resolved on demand through the proxy, as described below.

On-demand installs (the proxy)

Cealshell is a pure proxy — there is no central catalogue. Every install resolves owner:repoon demand through the remote's proxy, so any public repository that ships a .rbxm (or .rbxmx) is installable with no registration step:

Behind the scenes this hits the remote at /github/janisfox:marble@latest. GitHub is the default provider, so the prefix can be omitted; add codeberg/… to resolve through Codeberg (Forgejo/Gitea) instead.

The proxy is stateless — it resolves the reference, fetches the model, and returns it. There are no accounts, uploads, or download tracking involved in a proxied install.

Managing packages

Once packages are installed, manage them with:

updateknows what's installed and whether a newer version exists because each package records its owner, repo, version, provider and remote at install time, then re-resolves each one through the proxy.

Requiring packages

Installed packages are exposed through a single Packages module at the root of the scope they were installed into. Index it by package name — modules are required lazily and cached:

-- server packages (ServerStorage)
local Packages = require(game.ServerStorage.Packages)
local Signal = Packages.Signal

-- shared packages (ReplicatedStorage), e.g. installed with -s
local Shared = require(game.ReplicatedStorage.Packages)
local Promise = Shared.Promise

Packages.list() returns the names of everything installed in that scope. If your place already has a Packages instance, Cealshell uses CealPackages instead — install prints the exact require path every time.

Every installed instance is tagged so it's easy to find and manage:

• a Cealshell CollectionService tag, and
• CealshellPackage, CealshellOwner and CealshellVersion attributes.

Remotes

Packages are fetched from a single remote (default: https://api.cealshell.dev). Inspect and change it with the remote command:

To override the remote for one install only, prefix the reference with a host:

A prefix segment is treated as a remote when it looks like a host (a dot, a port, localhost, or an explicit http(s)://scheme); otherwise it's read as a provider (github/…, codeberg/…). A one-off override is recorded on the installed package, so update re-fetches it from the same place.

Command reference

Run --c help for this list in Studio, or --c manual <command> for details on any one.

Flag reference

Flags are consistent across commands and can be bundled (e.g. -sy):

Publishing a package

There's nothing to register — any public GitHub or Codeberg repository becomes installable as soon as it exposes a .rbxm or .rbxmx. There are two ways to do that:

1. Attach a release asset

Attach a .rbxm or .rbxmx file to a GitHub/Codeberg release. The proxy serves the newest release that ships one, preferring .rbxm if both are present. Release assets are pinned and immutable, which makes them the right choice for versioned packages.

2. Commit a cealshell.toml

If you'd rather not cut releases, commit a cealshell.tomlto the repository's default branch pointing at a model in the repo. When present, it takes precedence over releases:

[package]
version = "1.2.0"                 # required
rbxm = "dist/Marble.rbxm"         # required: repo-relative path, or a URL
name = "marble"                   # optional (defaults to the repo name)
description = "A bouncing marble" # optional
release_notes = "..."             # optional, shown as the install notes

Self-hosting the proxy

The proxy is open source. You can run your own instance and point Cealshell at it with remote set (or a one-off host prefix), so you never depend on a central service. It needs Node 18+ and PostgreSQL for a small version cache, and is otherwise stateless.

See the GitHub repository for the proxy source and setup instructions, including how to add a new source provider.