cascade_cli 0.1.4

Official Cascade CLI for cascadeci.com — login, init, doctor. Sealed Flutter CI client; see README for usage and how to support the project.

Cascade CLI

Official CLI for cascadeci.com
Sealed Flutter CI — ship releases with one commit tag.
Store credentials stay in GitHub secrets. Lanes stay in the Cascade dashboard.

---

Why Cascade?

Most Flutter CI dumps Play / App Store credentials into Actions YAML or sprawling workflows. Cascade flips that:

Without Cascade	With Cascade
Editable workflow owns every secret name	Sealed workflow — tampering is rejected
Store keys often live next to CI scripts	Credentials stay in GitHub secrets (opaque slots)
Intent buried in custom scripts	Intent in a commit tag + dashboard lanes
Guess whether a lane ran	Status + optional APK email from the control plane

Cascade is free. The CLI is the thin client that logs you in, seals your project, and keeps CI honest.

---

Quick start

# 1. Install
dart pub global activate cascade_cli

# 2. Sign up at https://cascadeci.com (email OTP), then:
cascade login

# 3. In your Flutter app root:
cascade init
cascade doctor

Then fill secrets, enable lanes in the dashboard, commit the sealed files, and push.

git add cascade.project.yaml .github/workflows/cascade.yml \
  cascade.secrets.env.example cascade.secrets.md
git commit -m "Add Cascade CI"
git push

---

Installation

Requirements

Need	Notes
Dart SDK ≥ 3.5 or Flutter SDK	Runs the cascade binary
Account on cascadeci.com	Real email + OTP (no disposable inboxes)
Flutter project	Run cascade init at the app root (pubspec.yaml)
GitHub repo + Actions	Hosts the sealed workflow
gh CLI	Push opaque secret slots

Activate

dart pub global activate cascade_cli

Ensure pub’s global bin directory is on your PATH (Dart prints it after activate). Verify:

cascade --help

Upgrade anytime with the same activate command.

Command vs package: you install package cascade_cli, then run the command cascade.

---

Commands

Command	What it does
cascade login	Browser / device approval against cascadeci.com
cascade init	Link app, write seal + sealed workflow + secrets guide
cascade doctor	Local health check (login, files, readiness)
cascade --help	Usage

---

Step-by-step

1 · Create your Cascade account

1. Open cascadeci.com/register
2. Choose Solo or Organization and complete email OTP
3. You do not need to create an app in the dashboard first — cascade init creates or links it

2 · Login

cascade login

Approve the device in the browser. The CLI stores a session token at:

~/.cascade/config.json

Never commit that file. Re-run cascade login on a new machine or after the token expires (web sessions last 8 hours; CLI tokens are separate).

3 · Init (Flutter app root)

cd /path/to/your_flutter_app
cascade init

What init writes

File	Purpose	Commit?
cascade.project.yaml	Opaque project seal (CI auth)	Yes
.github/workflows/cascade.yml	Sealed thin workflow	Yes — do not hand-edit
cascade.secrets.env.example	Safe template	Yes
cascade.secrets.md	Opaque slot map + gh commands	Yes
cascade.secrets.env	Your real values	No (gitignored)

Flags

Flag	When to use
--name MyApp	Display name for a new Cascade app
--new	Force a brand-new app (skip reuse by package / bundle)
--pick	Interactively choose when several apps match

cascade init
cascade init --name Roomround
cascade init --pick
cascade init --new --name ExperimentalBuild

4 · Secrets (opaque slots)

Store credentials live in GitHub Actions secrets, never in Cascade’s database.

1. Copy values into cascade.secrets.env (local only)
2. Follow cascade.secrets.md — it lists opaque slot names for gh secret set
3. Authenticate GitHub CLI once:

gh auth login
# then run the commands from cascade.secrets.md

Use only the slots from your project guide. Do not invent secret names.

5 · Enable lanes

In the Cascade dashboard:

• Open your app
• Enable only the deliveries you need (email, Play tracks, TestFlight, production, …)
• Closed lanes are denied at job-plan time, even if a commit tag asks for them

6 · Doctor

cascade doctor

Run after init, after changing secrets, or when CI looks wrong. Fix anything it reports before you push.

7 · Ship with a commit tag

Push a commit (tag optional). Cascade reads the leading intent; the matching dashboard lane must be on.

Commit intent	Typical outcome
(no tag)	Default: APK + email (when email lane is on)
[test-android-internal]	Play internal testing
[test-android-closed]	Play closed testing
[test-android-open]	Play open testing
[test-ios]	TestFlight
[build-apk]	APK only
[build-ios]	IPA only
[release-android-partial]	Production partial rollout
[release-android-full]	Production full rollout
[release-ios]	App Store

Example:

git commit -m "[build-apk] internal smoke"
git push

Results show on the app page and in notify email (including APK download links when configured).

---

How it fits together

  You (CLI)                 cascadeci.com              GitHub Actions
  ─────────                 ─────────────              ──────────────
  cascade login  ─────────►  device approve
  cascade init   ─────────►  create / link app
                 ─────────►  write seal + sealed YAML
  fill secrets   ───────────────────────────────►  gh secret set (opaque)
  enable lanes   ─────────►  dashboard toggles
  git push       ────────────────────────────────►  sealed workflow runs
                             ◄── job plan / status ──
                             ──► email / APK link

• Sealed workflow — checksummed. Edits → WORKFLOW_TAMPERED.
• Project seal — never shown in the dashboard UI; lives in cascade.project.yaml.
• Lanes — product control on Cascade; CI asks the control plane what is allowed.

---

Tips & troubleshooting

Situation	What to do
cascade not found	Add pub global bin to PATH, re-open the terminal
Login opens wrong host	Delete ~/.cascade/config.json, run cascade login again (recent CLI ignores dead localhost)
Green on GitHub, empty dashboard	Actions must reach https://cascadeci.com (not localhost)
Lane denied	Enable that lane on the app page, then re-push / re-run
Secrets missing	cascade doctor + cascade.secrets.md + gh secret list
Workflow edited	Restore official YAML via re-init; do not patch by hand

Full product onboarding: cascadeci.com/guide · cascadeci.com/docs

---

Support Cascade

Cascade stays free — all Flutter delivery lanes, no paywalls. Running the control plane (API, email, artifact storage) and maintaining this package still costs real money.

If Cascade helps you ship, you can support the project:

• Support page: cascadeci.com/support
• Contact: cascadeci.com/contact — mention Support Cascade
• Email: [e-mail]

Thank you for keeping Cascade available for Flutter teams.

---

Links

Product	cascadeci.com
Guide	cascadeci.com/guide
Docs	cascadeci.com/docs
Support	cascadeci.com/support
Package	pub.dev/packages/cascade_cli
Issues	GitHub issues

---

License

MIT © Cascade