docs: make dart run magic:artisan the canonical CLI invocation#92
Merged
Conversation
Magic ships an `artisan` executable (pubspec `executables: { artisan: }` + bin/artisan.dart), so every command runs as `dart run magic:artisan <cmd>` from any app that depends on magic, with no global activation and no <app> package-name placeholder. Replace the <app>:artisan / magic:magic forms across doc/ and README, drop the obsolete manual bin/artisan.dart Quick Start step (magic bundles it), and fix the stale global-activate tip.
…oject instructions SKILL.md, references/cli-commands.md, CLAUDE.md, and CLAUDE.local.md now describe the bundled `artisan` executable and the `dart run magic:artisan <cmd>` form (no <app> placeholder, no host-dispatcher wiring). Also corrects a wrong command name in CLAUDE.local.md (`magic:make:controller` -> `make:controller`).
The MagicInstallCommand dartdoc showed `dart run :artisan magic:install` (empty package prefix). Use the real `dart run magic:artisan magic:install` form.
There was a problem hiding this comment.
Pull request overview
Aligns Magic’s documentation with the intended CLI convention that Magic ships a bundled artisan executable, making dart run magic:artisan <command> the canonical invocation from any consuming app.
Changes:
- Standardizes CLI examples across docs and skills to use
dart run magic:artisan …. - Simplifies the README Quick Start by removing the obsolete per-app
bin/artisan.dartwrapper step and updating install/key generation examples. - Updates internal contributor docs (
CLAUDE.md) and a CLI command dartdoc example to match the canonical invocation.
Reviewed changes
Copilot reviewed 20 out of 20 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| skills/magic-framework/SKILL.md | Updates skill guidance and CLI section to the canonical dart run magic:artisan invocation. |
| skills/magic-framework/references/forms-validation.md | Updates FormRequest generation example to dart run magic:artisan …. |
| skills/magic-framework/references/cli-commands.md | Rewrites invocation guidance + all command examples to dart run magic:artisan …. |
| README.md | Updates Quick Start and CLI section examples to dart run magic:artisan … and removes obsolete wrapper step. |
| lib/src/cli/commands/magic_install_command.dart | Updates dartdoc usage examples to dart run magic:artisan …. |
| doc/security/authorization.md | Updates policy generation examples to dart run magic:artisan …. |
| doc/packages/magic-cli.md | Updates invocation and install/key/gen/make:* examples to dart run magic:artisan …. |
| doc/getting-started/service-providers.md | Updates make:provider example to dart run magic:artisan …. |
| doc/getting-started/installation.md | Updates scaffold/install instructions to use dart run magic:artisan … and removes <app> placeholder framing. |
| doc/eloquent/getting-started.md | Updates model generation examples to dart run magic:artisan …. |
| doc/digging-deeper/localization.md | Updates make:lang examples to dart run magic:artisan …. |
| doc/digging-deeper/events.md | Updates make:event/make:listener examples to dart run magic:artisan …. |
| doc/digging-deeper/encryption.md | Updates key generation example to dart run magic:artisan …. |
| doc/database/seeding.md | Updates make:seeder/make:factory examples to dart run magic:artisan …. |
| doc/database/migrations.md | Updates make:migration examples to dart run magic:artisan …. |
| doc/basics/views.md | Updates make:view examples to dart run magic:artisan …. |
| doc/basics/middleware.md | Updates make:middleware example to dart run magic:artisan …. |
| doc/basics/forms.md | Updates make:request tip example to dart run magic:artisan …. |
| doc/basics/controllers.md | Updates make:controller examples to dart run magic:artisan …. |
| CLAUDE.md | Updates contributor command table + CLI description to the canonical invocation. |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
…n executable The Introduction and Installation paragraphs still said commands run 'through your app's artisan dispatcher/entrypoint', conflicting with the canonical dart run magic:artisan form. Reword to magic's bundled artisan executable, noting app-level dispatcher aggregation as an optional alternative. Addresses PR #92 review.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Aligns all documentation with the framework's intended CLI convention:
dart run magic:artisan <command>.Magic declares an
artisanexecutable in itspubspec.yaml(executables: { artisan: }, backed bybin/artisan.dart, which bootsrunArtisanwithMagicArtisanProvider). So once a user addsmagicas a dependency, the full CLI is available viadart run magic:artisan <cmd>with no global activation and no app-specific<app>package-name placeholder. The source already used this form; the docs lagged behind (dart run <app>:artisanand straydart run magic:magic).Changes
doc/**,README.md,skills/magic-framework/**,CLAUDE.md, and alib/dartdoc:dart run <app>:artisan/dart run magic:magic/dart run :artisan->dart run magic:artisan.<app>placeholder ("replace with your package name"), the "host app's own artisan dispatcher" framing, and the staledart pub global activate magic_clitip now describe the bundledartisanexecutable.bin/artisan.dart" (magic ships it) and renumbered; bootstrap is now justdart run magic:artisan magic:install.CLAUDE.local.md(magic:make:controller->make:controller, local-only file) and theMagicInstallCommanddartdoc examples (dart run :artisan->dart run magic:artisan).Verification (local)
dart run <app>:artisan,magic:magic,dart run :artisan,magic:make:, or<app>placeholders across docs/skill/README/CLAUDE/lib.--root-dir doc --fallback-extensions md): 476 OK, 0 errors.dart analyze+dart formatclean on the touchedlib/file.Note
The install command keeps its registered name
magic:install, so the bootstrap readsdart run magic:artisan magic:install("magic" appears twice). That is accurate to the current command name; renaming it to a bareinstallwould be a separate code change (it would also affect the aggregated<app>:artisan magic:installform). Flagging in case you want that follow-up.