Installation
The BestSchoolUS CLI is a Node.js package. You need Node.js 18 or later installed on your machine. If you don't have Node.js, grab it from nodejs.org or use your OS package manager.
npx @bestschoolus/cli
to run any command without a global install. Or use pnpm / yarn — we support all major package managers.
System requirements
| Requirement | Minimum | Recommended |
|---|---|---|
| Node.js | 18.0.0 | 20.x LTS |
| npm | 8.0.0 | 10.x |
| OS | macOS, Linux, Windows (WSL recommended) | |
| Disk space | ~25 MB for CLI + dependencies | |
Authentication
BestSchoolUS uses OAuth authentication through your browser. When you run bsu login,
we open your default browser to our auth page where you sign in with your .edu email.
The token is stored locally in ~/.bsu/credentials.json.
BSU_TOKEN environment variable.
Supported email providers
We accept any email ending in .edu, as well as verified K-12
school district domains (e.g., @students.fcps.edu,
@pisd.edu, @naperville203.org).
This covers most US universities, community colleges, high schools, and middle schools.
International institutions and districts with non-standard domains can
contact us for manual verification.
Your First Deploy
Let's deploy a simple HTML page. Create a folder, add an index.html file,
and deploy it.
That's it. Your site is live with HTTPS, served from a CDN. Subsequent deploys from the same directory will update the same project automatically.
Deploying a framework project
If you're using a framework like React, Vue, or Astro, the CLI detects it and runs your build command automatically:
Configuration
Most projects need zero configuration. But if you need to customize build commands, output
directories, redirects, or headers, create a bsu.json file in your
project root.
Configuration options
| Field | Type | Description |
|---|---|---|
name | string | Project name (used for subdomain) |
build | string | Build command to run before uploading |
output | string | Directory containing built files (default: .) |
headers | object | Custom response headers by path pattern |
redirects | array | URL redirect rules |
routes | object | Rewrite rules for SPA routing |
env | object | Build-time environment variables |
ignore | array | Glob patterns for files to exclude from upload |
Projects
A project is a collection of files served from a single domain. Each project has its own subdomain, deploy history, analytics, and team members. Free accounts can create up to 10 projects.
Projects are identified by name (lowercase alphanumeric + hyphens). The name maps to your
subdomain: project my-portfolio becomes
my-portfolio.bestschoolus.com.
Project lifecycle
- Create —
bsu initcreates a project and links it to your directory - Deploy —
bsu deploypushes new files. Each deploy gets a unique build number - Update — Change settings, domains, or team members via CLI or dashboard
- Pause — Temporarily take a project offline. Files are preserved but not served
- Delete —
bsu rmpermanently removes the project and all deploys
Deploys & Builds
Every time you run bsu deploy, we create an immutable snapshot of your
files. This snapshot is assigned a sequential build number and pushed to the CDN. The
previous build stays available for instant rollback.
Build process
- CLI runs your build command (if configured)
- Output files are hashed and diffed against the previous deploy
- Only changed files are uploaded (incremental uploads)
- CDN cache is invalidated for changed paths
- SSL certificate is verified/renewed if needed
- New build goes live atomically
The entire process typically takes 2–8 seconds depending on project size and build complexity. We run builds on our infrastructure, not your machine, so build times are consistent regardless of your local hardware.
Preview deploys
Use bsu deploy --preview to create a preview URL without affecting
your production site. Preview URLs look like
preview-a3f2c1d.bestschoolus.com and expire after 7 days.
Useful for sharing WIP with teammates or professors before going live.
Domains
See the Platform Features page for full details on custom domains and SSL. Quick summary:
- Every project gets
projectname.bestschoolus.com - Add custom domains with
bsu domains add yourdomain.com - SSL certificates are automatic and free (Let's Encrypt)
- Multiple domains can point to one project
File Hosting
Any file in your deployed directory is accessible via URL. This makes BestSchoolUS a great option for hosting research data, course materials, or any file you need a stable link for.
Git-based Deploys
Connect a GitHub or GitLab repository to your project for automatic deploys on push.
Once connected, every push to main triggers a production deploy.
Pushes to other branches create preview deploys. You can customize which branches trigger
deploys in your project settings.
Team Projects
Invite collaborators by email. Each team member needs a BestSchoolUS account (free).
Rollbacks
Every deploy is immutable. Roll back to any previous build instantly:
Rollbacks are instant because we don't rebuild — we just point the CDN to a previous snapshot. Free plans retain the last 10 builds. Pro plans retain all builds indefinitely.
CLI Reference
| Command | Description |
|---|---|
bsu login | Authenticate via browser OAuth |
bsu logout | Clear stored credentials |
bsu init | Initialize new project in current directory |
bsu deploy | Build and deploy to production |
bsu deploy --preview | Create a preview deploy |
bsu ls | List your projects |
bsu logs [--follow] | View or tail access logs |
bsu domains add <domain> | Add custom domain |
bsu domains ls | List domains for current project |
bsu rollback <build> | Roll back to a specific build |
bsu deploys | List deploy history |
bsu team add <email> | Invite team member |
bsu team ls | List team members |
bsu env set KEY=VALUE | Set build environment variable |
bsu git connect <repo> | Connect GitHub/GitLab repo |
bsu rm | Delete current project |
bsu open | Open project URL in browser |
Limits & Quotas
| Resource | Free | Pro | Department |
|---|---|---|---|
| Storage | 5 GB | 50 GB | 200 GB |
| Bandwidth / month | 100 GB | 1 TB | 5 TB |
| Projects | 10 | 50 | Unlimited |
| Custom domains | 1 per project | 10 per project | Unlimited |
| Team members per project | 3 | 15 | Unlimited |
| Max file size | 100 MB | 500 MB | 2 GB |
| Build timeout | 5 min | 15 min | 30 min |
| Deploy retention | 10 builds | Unlimited | Unlimited |
| Analytics retention | 90 days | 1 year | 2 years |
FAQ
What happens when I graduate?
Your account stays active for 12 months after your .edu email stops working. After that, projects are paused (not deleted). You can reactivate by upgrading to a Pro plan or re-verifying with a new .edu email.
Can I use BestSchoolUS for a production app?
We're designed for static sites and files, not full-stack apps. If your app has a backend, you'll need to host that elsewhere and just use BSU for the frontend. That said, many students use BSU as their primary hosting with great results.
Is my content backed up?
Every deploy is stored in redundant object storage (3 copies across 2 regions). We also recommend keeping your source code in Git as an independent backup.
What's not allowed?
No malware, phishing, or illegal content. No crypto mining scripts. No sites that exist solely to game SEO. No hosting of copyrighted content you don't have rights to. See our Acceptable Use Policy for the full list.
How do you make money?
The free tier is funded by Pro and Department plan revenue plus university partnership agreements. We don't sell data, show ads, or inject anything into your sites.
Can I contribute?
The CLI is open source. Bug reports, feature requests, and pull requests are welcome on our GitHub. The platform itself is closed source but we publish our roadmap publicly.