tyro

Tyro

Tyro is the complete authentication, roles & privileges package for Laravel 12 & 13: a modern RBAC/ACL solution built on Laravel Sanctum, with a fantastic CLI that manages everything for you.

Set up in under a minute. No complicated configuration. No boilerplate.

Full documentation

• Instant install: one command bootstraps Sanctum, runs migrations, seeds roles & privileges, and prepares your User model.
• RBAC & ACL: unlimited roles with granular privileges; check access in controllers, middleware, Blade, or anywhere with $user->can(), hasRole(), hasPrivileges(), and more.
• 40+ Artisan commands: manage users, roles, privileges, tokens, suspensions, and audit logs from the CLI, perfect for automation and CI/CD.
• Ready for APIs: Sanctum token auth, REST endpoints for auth, user, role & privilege management, and a ready-made Postman collection.
• Middleware & Blade directives: role:, privilege:, ability: middleware plus 7 directives like @hasRole and @hasPrivilege.
• User suspension: freeze accounts instantly with an optional reason; all active tokens are revoked automatically, and users can be restored anytime.
• Audit trail: every role/privilege assignment, user suspension, and admin action is logged, with CLI commands to review and purge history.
• Security hardened: token abilities mirror roles & privileges, suspension instantly revokes tokens, and protected roles can't be deleted.
• Zero lock-in: publish config, migrations, and factories; disable API routes or CLI commands per environment.

Requirements

• PHP ^8.2
• Laravel 12 or 13
• Laravel Sanctum ^4.0

Installation (about a minute)

composer require hasinhayder/tyro
php artisan tyro:install

That's it. tyro:install sets up Sanctum, prepares your User model, runs migrations, and seeds the default roles & privileges, including a ready-to-use [email protected] superuser (password: tyro).

Want the ready-made API client? Run php artisan tyro:postman to open the official Postman collection.

Quick tour

Checking roles & privileges

$user->hasRole('admin');                                // check single role
$user->hasRoles(['admin', 'editor']);                  // must have ALL roles
$user->hasAnyRole(['admin', 'editor']);                // must have ANY role
$user->hasPrivilege('reports.run');                     // check single privilege
$user->hasPrivileges(['reports.run', 'billing.view']); // must have ALL privileges
$user->can('reports.run');                             // check privilege, role, or Laravel Gate

Managing roles & privileges

use HasinHayder\Tyro\Models\Role;
use HasinHayder\Tyro\Models\Privilege;

$user->assignRole($adminRole);                  // attach a role
$user->removeRole($editorRole);                 // detach a role
$role->privileges()->attach($privilege->id);    // grant a privilege
$role->privileges()->detach($privilege->id);    // revoke a privilege

Protecting routes

Route middleware aliases available out of the box:

Middleware Alias	Description
role:admin	User must possess the specified single role.
roles:admin,editor	User must possess any of the comma-separated roles.
privilege:reports.run	User must possess the specified single privilege.
privileges:reports.run,billing.view	User must possess any of the comma-separated privileges.
tyro.log	Log API requests into Tyro's audit trail.

Example route definitions:

Route::middleware(['auth:sanctum', 'role:admin'])->get('/admin', AdminController::class);
Route::middleware(['auth:sanctum', 'roles:admin,editor'])->get('/dashboard', DashboardController::class);
Route::middleware(['auth:sanctum', 'privilege:reports.run'])->get('/reports', ReportsController::class);
Route::middleware(['auth:sanctum', 'privileges:reports.run,billing.view'])->get('/finance', FinanceController::class);

Role & Privilege Helpers (HasTyroRoles)

In addition to basic role/privilege checks (hasRole, hasRoles, hasAnyRole, hasPrivilege, hasPrivileges, can), HasTyroRoles includes convenient helper methods:

…

Suspending users

$user->suspend('Pending account review');  // instantly revokes all tokens
$user->isSuspended();                      // true/false
$user->getSuspensionReason();
$user->unsuspend();

Auditing admin actions

Every role assignment, privilege change, suspension, and admin action is recorded automatically:

php artisan tyro:audit-list              # recent activity
php artisan tyro:audit-list --event=role.assigned
php artisan tyro:audit-purge             # purge logs per retention policy

Blade directives

Directive	Description
@hasRole('admin') ... @endhasRole	Check for a single role
@hasRoles(['admin', 'editor']) ... @endhasRoles	Check if user has ALL specified roles
@hasAnyRole(['admin', 'editor']) ... @endhasAnyRole	Check if user has ANY specified role
@hasPrivilege('reports.run') ... @endhasPrivilege	Check for a single privilege
@hasPrivileges(['reports.run', 'billing.view']) ... @endhasPrivileges	Check if user has ALL specified privileges
@hasAnyPrivilege(['reports.run', 'billing.view']) ... @endhasAnyPrivilege	Check if user has ANY specified privilege
@userCan('reports.run') ... @enduserCan	Check privilege, role, or Laravel Gate

@hasRole('admin')
    Welcome, Admin!
@endhasRole

@hasPrivilege('reports.run')
    View Reports
@endhasPrivilege

@hasRoles(['admin', 'editor'])
    Full editing permissions active.
@endhasRoles

CLI at a glance

One of Tyro's most powerful features: you can manage everything from the CLI (users, roles, privileges, tokens, suspensions, and audit logs) without touching the database directly. Perfect for automation, CI/CD pipelines, and incident response.

Users

Command	Description
tyro:user-create	Create a new user and attach Tyro's default role
tyro:user-list	Display all users tracked by Tyro
tyro:user-list-with-roles	Display users alongside their Tyro roles
tyro:user-show	Display a single user's details, roles, privileges, and suspension state
tyro:user-update	Modify a user's name, email, and password
tyro:user-delete	Delete a user while respecting the admin guardrails
tyro:user-suspend	Suspend a user (revokes all tokens)
tyro:user-unsuspend	Lift the suspension for a user
tyro:user-suspended	List every user currently suspended
tyro:user-token	Mint a Sanctum token without prompting for credentials
tyro:user-roles	Display a user's roles and their attached privileges
tyro:user-privileges	Display the privileges inherited by a user

Roles

Command	Description
tyro:role-create	Create a new role
tyro:role-list	Display all Tyro roles
tyro:role-list-with-privileges	Display each role along with its attached privileges
tyro:role-update	Modify a role name or slug
tyro:role-delete	Delete a role (except the protected ones)
tyro:role-attach	Attach a role to a user
tyro:role-detach	Detach a role from a user
tyro:role-users	Display every user assigned to the given role
tyro:role-purge	Truncate the roles and pivot tables without re-seeding
tyro:role-clone	Clone a role together with all of its privileges
tyro:role-sync	Synchronize a role's privileges with another role (supports --remove-extra and --dry-run; protected roles cannot be targets)

Privileges

Command	Description
tyro:privilege-create	Create a new Tyro privilege record
tyro:privilege-list	Display all Tyro privileges and their roles
tyro:privilege-update	Modify an existing privilege record
tyro:privilege-delete	Delete a Tyro privilege record
tyro:privilege-attach	Attach a privilege to a Tyro role
tyro:privilege-detach	Detach a privilege from a Tyro role
tyro:privilege-purge	Delete every privilege record and detach them from roles

Auth & Tokens

Command	Description
tyro:auth-login	Mint a Sanctum token for a user via the CLI
tyro:auth-logout	Delete a single Sanctum token (log out the corresponding session)
tyro:auth-logout-all	Delete every Sanctum token for a specific user
tyro:auth-logout-all-users	Revoke every Sanctum token issued for all users
tyro:who	Inspect which user a given token belongs to

Audit & Setup

Command	Description
tyro:audit-list	Display recent Tyro audit logs
tyro:audit-purge	Purge old Tyro audit logs
tyro:seed-all	Seed default roles, privileges, and bootstrap admin user
tyro:seed-roles	Seed default role definitions
tyro:seed-privileges	Seed default privilege definitions and role assignments
tyro:user-prepare	Add HasApiTokens and HasTyroRoles traits to the default User model
tyro:install	Bootstrap Tyro: set up Sanctum, run migrations, seed roles/privileges, and prepare your User model
tyro:publish-config	Publish Tyro's configuration file into your application
tyro:publish-migrations	Publish Tyro's migration files into your application
tyro:update-config	Update tyro config with the latest version
tyro:sys-version	Show the currently installed Tyro version
tyro:sys-about	Show Tyro's mission, version, and author details
tyro:setup-ai-skill	Install the Tyro Authorization AI skill for your preferred agent
tyro:doc	Open the Tyro documentation in your browser
tyro:postman	Open the Tyro Postman collection in your browser
tyro:star	Open the Tyro GitHub repository so you can star it
tyro:run-tests	Run your project's automated tests (Pest by default)

Run php artisan list tyro to see every available command. Most commands also have shorter aliases (for example, tyro:login, tyro:users, tyro:roles, tyro:me, tyro:audit).

Optional: REST API

Tyro ships REST endpoints for auth, user management, and role/privilege CRUD (enabled by default, prefix api). Disable them whenever you want:

TYRO_DISABLE_API=true

Configuration

Publish and customize everything:

php artisan vendor:publish --tag=tyro-config
php artisan vendor:publish --tag=tyro-migrations

If you want to update your published configuration later when new options are introduced, you can run:

php artisan tyro:update-config

Every option in config/tyro.php

API & routes

Env var	Default	Description
TYRO_DISABLE_API	false	Skip loading Tyro's REST routes entirely
TYRO_DISABLE_COMMANDS	false	Skip registering Tyro's artisan commands
TYRO_GUARD	sanctum	Guard used by Tyro's protected routes
TYRO_ROUTE_PREFIX	api	Prefix for Tyro's REST routes
TYRO_ROUTE_NAME_PREFIX	tyro.	Prefix for Tyro's route names

Users & roles

Env var	Default	Description
TYRO_USER_MODEL, AUTH_MODEL	App\Models\User	User model Tyro operates on
DEFAULT_ROLE_SLUG	user	Role slug attached to newly registered users
TYRO_USERS_TABLE	users	Table name used for suspension columns

Passwords

Env var	Default	Description
TYRO_PASSWORD_MIN_LENGTH	8	Mi