██████╗ ██████╗ █████╗ ██████╗██╗ ██╗██╗ █████╗ ██████╗
██╔═══██╗██╔══██╗██╔══██╗██╔════╝██║ ██║██║ ██╔══██╗██╔══██╗
██║ ██║██████╔╝███████║██║ ██║ ██║██║ ███████║██████╔╝
██║ ██║██╔══██╗██╔══██║██║ ██║ ██║██║ ██╔══██║██╔══██╗
╚██████╔╝██║ ██║██║ ██║╚██████╗╚██████╔╝███████╗██║ ██║██║ ██║
╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚══════╝╚═╝ ╚═╝╚═╝ ╚═╝
Project scaffolding and script runner for Arcane-based Flutter and Dart applications.
- Project Scaffolding - Create production-ready Flutter and Dart projects
- Script Runner - Execute pubspec.yaml scripts with fuzzy matching
- Multi-Project Architecture - Client, models, and server packages
- Firebase Integration - Automated setup and deployment
- Platform Selection - Choose which platforms to target
Oracular/
├── oracular/ Dart CLI tool
├── docs/ Documentation and guides
└── templates/ Project templates (editable)
├── arcane_app/ Basic multi-platform Flutter app
├── arcane_beamer_app/ Beamer navigation Flutter app
├── arcane_dock_app/ Desktop system tray app
├── arcane_jaspr_app/ Jaspr web application
├── arcane_jaspr_docs/ Jaspr static documentation site
├── arcane_cli_app/ Dart CLI application
├── arcane_models/ Shared data models package
└── arcane_server/ Shelf-based REST API server
dart pub global activate oracularEvery release ships per-template ZIPs to the
GitHub Releases page.
If you just want a project skeleton — no oracular install required —
you can download a ZIP for one template, extract it, and run the
bundled setup.dart:
# 1. Grab the ZIP for your template (replace <X.Y.Z> with the latest version)
curl -fLO https://github.com/ArcaneArts/oracular/releases/latest/download/arcane_app-v<X.Y.Z>.zip
# 2. Extract + setup
unzip arcane_app-v<X.Y.Z>.zip -d /tmp/my_app-extract
cd /tmp/my_app-extract
dart run setup.dart --name my_app --org com.example --output-dir ~/code/my_appsetup.dart does the same thing the interactive wizard does — placeholder
replacement, jaspr render-mode patching, optional models/server companions,
pub get — but takes its inputs from flags so it works on CI or any machine
with the Dart SDK. The script ends with an optional offer to install
oracular itself pinned to the same release version for easier ongoing
work. See SETUP_USAGE.md inside each ZIP for the full flag reference.
Releases are produced automatically by .github/workflows/templates-release.yml
on every commit that contains [Build] in its message. The ZIP version
matches oracular/pubspec.yaml, so the templates and CLI stay in lockstep.
# Interactive wizard
oracular
# Create project directly
oracular create app --name my_app --org com.exampleFrom oracular/, plain dart test is the safe default: it skips live
Firebase/GCP deployment suites and keeps local validation on unit tests,
template copy/permutation checks, and non-deploying compile checks.
Run live deployment tests only when you intend to mutate the shared Firebase test project and have credentials in place:
cd oracular
ORACULAR_RUN_DEPLOYMENT_TESTS=1 dart test -P live-deployment test/integration/deploymentoracular # Interactive wizard
oracular create app # Create project with prompts
oracular create templates # List available templatesGenerated projects include GET_STARTED.md, plus shortcut commands for the
folders and setup consoles users need next.
oracular guide # Regenerate the setup guide
oracular guide --print # Print the guide in the terminal
oracular open guide # Open GET_STARTED.md
oracular open app # Open the main app folder
oracular open firebase # Open Firebase project overview
oracular open auth # Open Firebase Authentication
oracular open firestore # Open Firestore Database
oracular open storage # Open Firebase Storage
oracular open hosting # Open Firebase Hosting
oracular open server # Open the server package
oracular open service-account # Open Firebase service account keys
oracular open cloud-run # Open Google Cloud RunRun scripts defined in your pubspec.yaml:
oracular scripts list # List all scripts
oracular scripts exec build # Run a script
oracular scripts exec br # Abbreviation (build_runner)
oracular scripts exec tv # Abbreviation (test_verbose)Supports fuzzy matching and abbreviations (first letter of each word).
oracular check tools # Verify all CLI tools
oracular check flutter # Check Flutter installation
oracular check firebase # Check Firebase CLI
oracular check docker # Check Docker
oracular check gcloud # Check Google Cloud SDK
oracular check doctor # Run flutter doctor
oracular check billing # Detect Spark vs Blaze billing planEnd-to-end one-command setup (works for Flutter web + Jaspr static & client):
oracular deploy firebase-setup-full # Login, billing check, FlutterFire/
# Jaspr JS SDK config, Firestore +
# Storage bootstrap, rules deploy,
# web build, release + beta hosting,
# Cloud Run APIs + cleanup. Idempotent.Each stage is independently re-runnable:
oracular deploy firestore-init # Create the default Firestore DB
oracular deploy storage-init # Create the default Storage bucket
oracular deploy auth-providers # Email + Google sign-in hand-off
oracular deploy firestore # Deploy Firestore rules + indexes
oracular deploy storage # Deploy Storage rules
oracular deploy hosting-init # Create `<project>-beta` site
oracular deploy hosting # Build web + deploy release channel
oracular deploy hosting-beta # Build web + deploy beta channel
oracular deploy all # Deploy all Firebase rulesoracular deploy server-setup # Generate Docker configs + scripts
oracular deploy server-build # Build production Docker image
oracular deploy artifact-cleanup # Apply Artifact Registry cleanup policy
oracular deploy cloudrun-prune # Cap Cloud Run revisionsThe generated script_deploy.sh runs both cleanup steps automatically
after every deploy.
| Template | Platforms | Description |
|---|---|---|
| Basic Arcane | All | Multi-platform app with Arcane UI |
| Beamer Navigation | All | Declarative routing with Beamer |
| Desktop Tray | Desktop | System tray/menu bar application |
| Template | Output | Description |
|---|---|---|
| Jaspr Web App | SPA | Interactive web application with Arcane Jaspr |
| Jaspr Docs | Static | Documentation site with markdown support |
| Template | Description |
|---|---|
| Dart CLI | Command-line interface application |
- Models Package - Shared data models for client and server
- Server App - Shelf-based REST API with Firebase integration
Not sure which platform to use? See our comprehensive Platform Comparison Guide for detailed pros/cons analysis.
Quick Decision:
- Need native mobile/desktop apps? Use Flutter + Arcane
- Building a website with SEO requirements? Use Jaspr + Arcane Jaspr
- Want fast initial page loads? Use Jaspr + Arcane Jaspr
- Need offline-first functionality? Use Flutter + Arcane
Add scripts to your pubspec.yaml:
scripts:
build: flutter build web --release
deploy: firebase deploy --project my-project
build_runner: dart run build_runner build --delete-conflicting-outputs
test_verbose: dart test --reporter=expanded
pod_install: cd ios && pod install --repo-updateThen run with abbreviations:
oracular scripts exec b # build (unique prefix)
oracular scripts exec br # build_runner
oracular scripts exec tv # test_verbose
oracular scripts exec pi # pod_installSee the CLI Development README.
MIT