Chapter 30: Tina4 CLI#

1. Getting a New Developer Up to Speed#

Monday morning. A new developer joins your team. You hand them the repo URL. By 10am they have a running project, a new database model, CRUD routes, a migration, and a deployment to staging. All from the command line. No documentation scavenger hunt. No boilerplate copy-paste.

The Tina4 CLI is a single Rust binary. It manages all four Tina4 frameworks (PHP, Python, Ruby, Node.js). The commands are identical across languages. Learn the CLI for Node.js. You know it for Python.

2. tina4 init -- Project Scaffolding#

You saw this in Chapter 1. Now the details.

bash

tina4 init my-project

Creating Tina4 project in ./my-project ...  Detected language: Node.js (package.json)  Created .env  Created .env.example  Created .gitignore  Created src/routes/  Created src/orm/  Created migrations/  Created src/seeds/  Created src/templates/  Created src/templates/errors/  Created src/public/  Created src/public/js/  Created src/public/css/  Created src/public/scss/  Created src/public/images/  Created src/public/icons/  Created src/locales/  Created data/  Created logs/  Created secrets/  Created tests/Project created! Next steps:  cd my-project  npm install  tina4 serve

Language Detection#

The CLI detects the language from existing files:

File Present	Language
`composer.json`	PHP
`pyproject.toml` or `requirements.txt`	Python
`Gemfile`	Ruby
`package.json`	Node.js

If no language-specific file exists, the CLI asks:

bash

tina4 init my-project

No language detected. Which language?  1. PHP  2. Python  3. Ruby  4. Node.js> 4Creating Tina4 Node.js project in ./my-project ...

Explicit Language Selection#

Skip the prompt by specifying the language:

bash

tina4 init nodejs my-project

This creates a Node.js project with package.json, app.ts, and the full directory structure.

Init into an Existing Directory#

Already have a project? Add Tina4 structure:

bash

cd existing-projecttina4 init .

The CLI creates only files and directories that do not exist. It never overwrites.

3. tina4 serve -- Dev Server#

bash

tina4 serve

  Tina4 Node.js v3.10.3  HTTP server running at http://0.0.0.0:7148  WebSocket server running at ws://0.0.0.0:7148  Live reload enabled  Press Ctrl+C to stop

tina4 serve detects the language and starts the appropriate server. For Node.js, it spawns the Tina4 Node.js runtime with SCSS compilation, file watching, and live reload all wired in.

Options#

bash

tina4 serve --port 8080        # Custom porttina4 serve --host 127.0.0.1   # Bind to localhost onlytina4 serve --production       # Production mode (no live reload, debug off)

Bypassing the CLI#

The framework refuses to start without the Rust CLI. For sandboxed environments (Docker images, CI runners) set TINA4_OVERRIDE_CLIENT=true in .env and only then run:

bash

TINA4_OVERRIDE_CLIENT=true npx tsx app.ts

This bypasses SCSS compilation and live reload, so use it only when the Rust CLI is genuinely unavailable.

4. tina4 generate model -- ORM Scaffolding#

The generate model command creates an ORM model file and a matching migration. One command produces both.

bash

tina4 generate model Product

Created src/orm/Product.tsCreated migrations/20260322120000_create_products_table.sql

The generated model:

typescript

import { BaseModel } from "tina4-nodejs/orm";export class Product extends BaseModel {    static tableName = "products";    static primaryKey = "id";    id!: number;    createdAt!: string;    updatedAt!: string;}

The generated migration:

sql

-- UPCREATE TABLE products (    id INTEGER PRIMARY KEY AUTOINCREMENT,    created_at TEXT DEFAULT CURRENT_TIMESTAMP,    updated_at TEXT DEFAULT CURRENT_TIMESTAMP);-- DOWNDROP TABLE IF EXISTS products;

The model is ready to use. Add your fields and run migrations.

Adding Fields#

Specify fields on the command line:

bash

tina4 generate model Product --fields "name:string,price:float,category:string,inStock:bool"

The generated model includes all the fields:

typescript

import { BaseModel } from "tina4-nodejs/orm";export class Product extends BaseModel {    static tableName = "products";    static primaryKey = "id";    id!: number;    name!: string;    price!: number;    category!: string;    inStock!: boolean;    createdAt!: string;    updatedAt!: string;}

And the migration:

sql

-- UPCREATE TABLE products (    id INTEGER PRIMARY KEY AUTOINCREMENT,    name TEXT NOT NULL DEFAULT '',    price REAL NOT NULL DEFAULT 0,    category TEXT NOT NULL DEFAULT '',    in_stock INTEGER NOT NULL DEFAULT 0,    created_at TEXT DEFAULT CURRENT_TIMESTAMP,    updated_at TEXT DEFAULT CURRENT_TIMESTAMP);-- DOWNDROP TABLE IF EXISTS products;

Field Types#

CLI Type	TypeScript Type	SQLite Column
`string`	`string`	`TEXT`
`int`	`number`	`INTEGER`
`float`	`number`	`REAL`
`bool`	`boolean`	`INTEGER`
`text`	`string`	`TEXT`
`date`	`string`	`TEXT`

Options#

Flag	Description	Example
`--fields`	Comma-separated field definitions	`--fields "name:string,price:float"`
`--auto-crud`	Enable auto-CRUD on the model	`--auto-crud`
`--soft-delete`	Add soft delete support	`--soft-delete`
`--no-migration`	Skip migration generation	`--no-migration`
`--with-route`	Also generate a CRUD route file	`--with-route`

5. tina4 generate route -- CRUD Route Scaffolding#

The generate route command creates a complete CRUD route file with all five REST endpoints. It reads the model's properties and builds routes with proper imports and response handling.

bash

tina4 generate route products

Created src/routes/products.ts

The generated route file:

typescript

import { Router } from "tina4-nodejs";Router.get("/api/products", async (req, res) => {    const page = parseInt(req.query.page ?? "1", 10);    const perPage = parseInt(req.query.per_page ?? "20", 10);    const offset = (page - 1) * perPage;    const products = await Product.findAll({ limit: perPage, offset });    const results = products.map(p => p.toDict());    return res.json({        data: results,        page,        per_page: perPage,        count: results.length    });});Router.get("/api/products/{productId:int}", async (req, res) => {    const product = await Product.findById(req.params.productId);    if (product === null) {        return res.status(404).json({ error: "Product not found" });    }    return res.json(product.toDict());});Router.post("/api/products", async (req, res) => {    const body = req.body;    const product = new Product();    product.name = body.name ?? "";    product.price = parseFloat(body.price ?? "0");    product.category = body.category ?? "";    product.inStock = Boolean(body.inStock ?? false);    await product.save();    return res.status(201).json(product.toDict());});Router.put("/api/products/{productId:int}", async (req, res) => {    const product = await Product.findById(req.params.productId);    if (product === null) {        return res.status(404).json({ error: "Product not found" });    }    const body = req.body;    if (body.name !== undefined) product.name = body.name;    if (body.price !== undefined) product.price = parseFloat(body.price);    if (body.category !== undefined) product.category = body.category;    if (body.inStock !== undefined) product.inStock = Boolean(body.inStock);    await product.save();    return res.json(product.toDict());});Router.delete("/api/products/{productId:int}", async (req, res) => {    const product = await Product.findById(req.params.productId);    if (product === null) {        return res.status(404).json({ error: "Product not found" });    }    await product.delete();    return res.status(204).end();});

The generator reads the model's properties and creates routes with type casting and null checks. Customize the generated code immediately. It is regular TypeScript, not magic.

Options#

Flag	Description	Example
`--prefix`	Custom route prefix (default: `/api`)	`--prefix /api/v2`
`--middleware`	Add middleware to all routes	`--middleware authMiddleware`

6. tina4 generate migration -- Migration Scaffolding#

The generate migration command creates a timestamped migration file with UP and DOWN sections. The timestamp ensures migrations run in order.

bash

tina4 generate migration add_category_to_products

Created migrations/20260322120500_add_category_to_products.sql

The generated file:

sql

-- UP-- Add your forward migration SQL here-- DOWN-- Add your rollback migration SQL here

Fill in the SQL:

sql

-- UPALTER TABLE products ADD COLUMN category TEXT DEFAULT '';-- DOWNALTER TABLE products DROP COLUMN category;

The timestamp prefix (20260322120500) ensures migrations run in order. Each migration runs once. The framework tracks which ones have been applied.

When to Generate a Migration#

Generate a new migration when you need to change the database schema after the initial model migration. Adding a column. Creating an index. Renaming a table. Each change gets its own migration file with a unique timestamp.

7. tina4 generate middleware -- Middleware Scaffolding#

The generate middleware command creates a middleware function with the correct signature and a placeholder for your logic.

bash

tina4 generate middleware rateLimit

Created src/middleware/rateLimit.ts

The generated file:

typescript

import { Middleware } from "tina4-nodejs";async function rateLimit(req: any, res: any, next: Function) {    // Add your middleware logic here    // Continue to the next middleware or route handler    return next();    // Or return early to block the request:    // return res.status(429).json({ error: "Rate limit exceeded" });}export default rateLimit;

The middleware is a named function. Reference it in route definitions:

typescript

Router.get("/api/data", async (req, res) => {    return res.json({ data: "protected" });}, "rateLimit");

8. Generate All at Once#

Combine flags to generate multiple files in a single command:

bash

tina4 generate model Product --with-route --with-migration

Created src/orm/Product.tsCreated src/routes/products.tsCreated migrations/20260322120000_create_products_table.sql

Model. CRUD routes. Migration. All wired together. Ready to use.

9. tina4 doctor -- Health Check#

The doctor command checks your project for common issues:

bash

tina4 doctor

Tina4 Doctor -- Checking your project...  [OK] Node.js v20.11.1 detected  [OK] npm package manager found  [OK] tina4-nodejs package installed (v3.10.3)  [OK] .env file exists  [OK] Database connection: sqlite:///data/app.db  [OK] Database is accessible  [OK] src/routes/ directory exists (3 route files)  [OK] src/orm/ directory exists (2 model files)  [OK] src/templates/ directory exists (5 templates)  [OK] src/public/ directory exists (static files served)  [OK] tests/ directory exists (4 test files)  [WARN] No migrations found in migrations/  [OK] AI context: Claude Code detected, CLAUDE.md present  [OK] .gitignore includes .env, data/, logs/  12 checks passed, 1 warning, 0 errors

Doctor checks:

Node.js version and package manager
Tina4 package installation and version
.env file existence and critical variables
Database connectivity
Directory structure
Missing files or configurations
AI tool context files
Git configuration

The warnings give actionable advice. If your database is not configured, it tells you exactly what to add to .env.

10. tina4 test -- Running Tests#

bash

tina4 test

Running tests...  ProductTest    [PASS] test_create_product    [PASS] test_load_product  2 tests, 2 passed, 0 failed (0.12s)

This runs all tests in the tests/ directory. See Chapter 18 for full testing documentation.

Test Options#

bash

tina4 test --filter ProductTest            # Specific test classtina4 test --verbose                       # Show assertion details

Or use npm:

bash

npm test

11. tina4 routes -- Route Listing#

See all registered routes in your project:

bash

tina4 routes

Registered Routes:  Method  Path                        Handler                     Middleware  ------  --------------------------  --------------------------  ----------  GET     /health                     healthCheck                 -  GET     /api/products               listProducts                ResponseCache:300  GET     /api/products/{productId}   getProduct                  -  POST    /api/products               createProduct               authMiddleware  PUT     /api/products/{productId}   updateProduct               authMiddleware  DELETE  /api/products/{productId}   deleteProduct               authMiddleware  GET     /api/auth/login             -                           -  POST    /api/auth/login             login                       -  GET     /admin                      adminDashboard              -  9 routes registered

This is useful for verifying that your routes are registered and for finding the handler function for a specific URL.

Filtering#

bash

tina4 routes --method POST          # Filter by HTTP methodtina4 routes --filter products      # Filter by path patterntina4 routes --middleware auth      # Filter by middleware

When debugging routing issues, check here first. If a route does not match, tina4 routes shows whether it was registered and what middleware is attached.

12. tina4 migrate -- Database Migrations#

Run pending migrations:

bash

tina4 migrate

Running migrations...  [UP] 20260322000100_create_users_table.sql  [UP] 20260322000200_create_products_table.sql  [UP] 20260322000300_add_category_to_products.sql  3 migrations applied

Rollback#

bash

tina4 migrate --rollback

Rolling back last migration...  [DOWN] 20260322000300_add_category_to_products.sql  1 migration rolled back

Migration Table Auto-Upgrade#

If your project was created with an early v3 release, the tina4_migration tracking table may use the older two-column schema. Running tina4 migrate detects the old layout and adds the missing migration_id, batch, and executed_at columns, backfilling existing data. No manual intervention needed.

Status#

bash

tina4 migrate --status

Migration Status:  Status    Migration  --------  -----------------------------------------  Applied   20260322000100_create_users_table.sql  Applied   20260322000200_create_products_table.sql  Applied   20260322000300_add_category_to_products.sql  Pending   20260322000400_create_orders_table.sql  3 applied, 1 pending

13. tina4 queue -- Queue Management#

bash

tina4 queue work                        # Start processing jobstina4 queue work --queue send-email     # Process specific queuetina4 queue:dead                        # List dead letter jobstina4 queue:retry 42                    # Retry a dead jobtina4 queue:clear --older-than 7d       # Clear old dead jobs

14. tina4 build -- Production Build#

bash

tina4 build

Compiles TypeScript to JavaScript. Bundles for production. Optimizes:

Building for production...  Compiled 47 TypeScript files  Output: dist/  Size: 245KBReady for deployment:  node dist/app.js

15. Custom CLI Commands#

Create custom seed scripts as standalone TypeScript files:

typescript

// scripts/seed-products.tsimport { Database } from "tina4-nodejs/orm";async function seedProducts() {    const db = Database.getConnection();    const products = [        { name: "Keyboard", price: 79.99 },        { name: "Mouse", price: 29.99 },        { name: "Monitor", price: 399.99 }    ];    for (const p of products) {        await db.execute(            "INSERT INTO products (name, price) VALUES (:name, :price)",            p        );    }    console.log(`Seeded ${products.length} products`);}seedProducts();

Run it:

bash

npx tsx scripts/seed-products.ts

16. Exercise: Scaffold a Feature in 5 Commands#

Scaffold a complete "Customer" feature from scratch using only CLI commands.

Requirements#

Starting from an existing Tina4 Node.js project, run 5 commands to create:

A Customer ORM model with name, email, phone, and company fields
A CRUD route file with all five REST endpoints
A migration that creates the customers table
Run the migration to create the table
Run the doctor to verify everything

Expected Commands#

bash

# 1. Generate the model with route and migrationtina4 generate model Customer --with-route --with-migration# 2. Edit the model to add fields (manual step)# Add fields to src/orm/Customer.ts# 3. Edit the migration to add columns (manual step)# Add columns to the migration file# 4. Run the migrationtina4 migrate# 5. Run the doctor to verify everything is set uptina4 doctor

Solution#

Command 1: Generate everything:

bash

tina4 generate model Customer --with-route --with-migration

Command 2: Edit src/orm/Customer.ts:

typescript

import { BaseModel } from "tina4-nodejs/orm";export class Customer extends BaseModel {    static tableName = "customers";    static primaryKey = "id";    id!: number;    name!: string;    email!: string;    phone!: string;    company!: string;    createdAt!: string;}

Command 3: Edit the migration file:

sql

-- UPCREATE TABLE customers (    id INTEGER PRIMARY KEY AUTOINCREMENT,    name TEXT NOT NULL,    email TEXT NOT NULL UNIQUE,    phone TEXT,    company TEXT,    created_at TEXT DEFAULT CURRENT_TIMESTAMP);CREATE INDEX idx_customers_email ON customers(email);-- DOWNDROP TABLE IF EXISTS customers;

Command 4: Run the migration:

bash

tina4 migrate

Running migrations...  [UP] 20260322120000_create_customers_table.sql  1 migration applied

Command 5: Verify with doctor:

bash

tina4 doctor

  [OK] src/orm/ directory exists (3 model files)  [OK] src/routes/ directory exists (4 route files)  [OK] Database connection: sqlite:///data/app.db  ...

Now test the API:

bash

curl -X POST http://localhost:7148/api/customers \  -H "Content-Type: application/json" \  -d '{"name": "Alice Corp", "email": "alice@corp.com", "phone": "+1-555-0100", "company": "Alice Corp"}'

json

{  "id": 1,  "name": "Alice Corp",  "email": "alice@corp.com",  "phone": "+1-555-0100",  "company": "Alice Corp",  "created_at": "2026-03-22 12:00:00"}

From zero to a working CRUD API. Five commands. Under two minutes.

17. Gotchas#

1. tina4 Command Not Found#

Problem: Running tina4 gives "command not found".

Cause: The Tina4 CLI is not installed or not in your PATH.

Fix: Install the CLI: curl -fsSL https://tina4.com/install.sh | sh. Verify with tina4 --version. If installed but not found, add the installation directory to your PATH:

bash

echo 'export PATH="$HOME/.tina4/bin:$PATH"' >> ~/.zshrcsource ~/.zshrc

2. Wrong Language Detected#

Problem: tina4 init creates a PHP project instead of Node.js.

Cause: A composer.json file exists in the directory from a previous project.

Fix: Use explicit language selection: tina4 init nodejs my-project. Or delete the conflicting language file before running init.

3. Generated Files Overwrite Existing Code#

Problem: Running tina4 generate route products overwrites your custom route file.

Cause: The generate command creates files at fixed paths. If the file exists, it is overwritten.

Fix: The CLI warns you before overwriting. Check if the file exists first. If you need to regenerate, rename the existing file: mv src/routes/products.ts src/routes/products_backup.ts.

4. Migration Order Issues#

Problem: A migration fails because it references a table that does not exist yet.

Cause: Migration files run in alphabetical (timestamp) order. If migration B depends on a table created by migration A, but A has a later timestamp, B runs first and fails.

Fix: Use consistent timestamps. The tina4 generate migration command uses the current timestamp. Generating migrations in order ensures correct execution order. If you need to fix ordering, rename the migration files to adjust their timestamps.

5. tina4 serve Uses Wrong Port#

Problem: tina4 serve starts on port 7148 but you need port 8080.

Cause: The default port is 7148 unless overridden.

Fix: Set it in .env: TINA4_PORT=8080. Or pass it as a flag: tina4 serve --port 8080. The .env value takes precedence over the default. The command-line flag overrides everything.

6. Doctor Shows False Warnings#

Problem: tina4 doctor warns about missing migrations, but your project does not use migrations.

Cause: Doctor checks for common conventions. It warns about missing migrations regardless of your approach.

Fix: These are warnings, not errors. Ignore warnings that do not apply to your project. Doctor is a guide, not a gatekeeper.

7. Model Name Must Be PascalCase#

Problem: tina4 generate model order_item creates a model class named order_item which is not valid TypeScript convention.

Cause: The CLI uses the argument as-is for the class name.

Fix: Use PascalCase for model names: tina4 generate model OrderItem. The CLI converts it to snake_case for the table name (order_items).

8. Build Fails#

Fix: Check TypeScript errors with npx tsc --noEmit.

9. Port Conflict#

Fix: Use tina4 serve --port 8080 or set TINA4_PORT in .env.

18. Documentation#

bash

tina4 docs      # Download framework-specific book chapters to .tina4-docs/tina4 books     # Download the complete Tina4 book (all languages) to tina4-book/

tina4 docs detects your project language and downloads only the relevant chapters. The documentation is available in Markdown format, optimised for AI tools and local reference.

19. Test Port (Dual-Port Development)#

When TINA4_DEBUG=true, Tina4 automatically starts a second HTTP server on port + 1000:

Main port (e.g. 7148): hot-reload enabled, for AI dev tools
Test port (e.g. 8148): stable, no hot-reload, for user testing

This prevents the browser from refreshing mid-test when AI tools edit files.

Setting	Effect
`TINA4_NO_AI_PORT=true`	Disables the test port entirely
`TINA4_NO_RELOAD=true`	Disables hot-reload on the main port too
`--no-reload`	CLI flag equivalent of TINA4NORELOAD