Tina4 CLI reference#

The Tina4 client is one signed binary for Python, PHP, Ruby, Node.js, and tina4-js. It creates projects, starts servers, manages local tooling, and measures source code without loading a framework runtime.

Install the client#

macOS and Linux:

curl -fsSL https://tina4.com/install.sh | sh

Windows PowerShell:

irm https://tina4.com/install.ps1 | iex

Check the installed version:

tina4 --version

Command map#

Run tina4 <command> --help for the command's current arguments and options.

Start a project#

One command creates the project. One command runs it.

tina4 init python my-appcd my-apptina4 serve

Replace python with php, ruby, nodejs, or js. The js option creates a tina4-js front-end project.

tina4 serve detects the framework from the project files. You can also name a configured project from another directory:

tina4 serve my-app

Common server options:

Measure code health#

tina4 metrics reads source files directly. It does not start the application or import the framework. One native engine applies the same formulas to Python, PHP, Ruby, TypeScript/JavaScript, and Rust.

Run it from a project:

tina4 metrics

Scan an explicit source directory and show the ten highest-ranked findings:

tina4 metrics --path src --top 10

The report measures lines of code, cyclomatic complexity, maintainability, coupling, function count, duplicate blocks, and test-reference evidence. It reports evidence that a test refers to a source file. It does not claim that the test ran, passed, or covered each branch.

Metrics options#

Production scans ignore conventional tests, specs, generated bundles, minified assets, declarations, dependencies, build output, caches, and version-control data. Use explicit exclusions for project-specific production trees:

tina4 metrics --exclude '**/dev_admin/**' --exclude '**/gallery/**'

CI gate#

Use JSON for stored reports and --fail-on for the gate:

tina4 metrics --json --fail-on error > metrics.json

--top changes presentation only. It never hides a finding from the exit gate. Informational no_test_reference findings do not fail warning or error gates.

Track change over time#

Every scan records a snapshot to .tina4-metrics.json in the scan root. The next scan of the same scope reads it and prints a Since last run block: offenders, duplicate lines, average maintainability, and average complexity, each marked better, worse, or same, followed by the files that improved or regressed.

tina4 metrics --path src        # first run: writes the baseline# ... you refactor ...tina4 metrics --path src        # second run: reports what moved

The snapshot is data, not source, so the engine never scans it. Commit it to gate regressions in review, or add it to .gitignore for a local-only baseline. The --json output carries the same comparison under a delta key. Pass --no-history to read and write nothing.

Reading offender totals#

An offender is one finding, not one file. A file can carry several findings: high function complexity, excessive size, low maintainability, duplication, and too many functions. Count unique file names when you need the size of the refactoring worklist. Count findings when you need the gate pressure.

Pre-check security with CodeQL#

tina4 codeql runs the same CodeQL scan your pull request will meet in CI, on your own machine, before you push. It reads the checkout, decides which languages are present, and hands each one to CodeQL for the GitHub "default setup (extended)" security suite. A finding shows here first, so it never has to surface as a red check later.

The command needs the CodeQL client on the path. Install it, with the query packs it depends on, in one step:

tina4 install codeql

Then run it from a project:

tina4 codeql

It detects the language from the project files. A Node.js or tina4-js tree is scanned as JavaScript and TypeScript, a Python tree as Python, a Ruby tree as Ruby, and the GitHub Actions workflows are scanned too when .github/workflows exists. For each one the command creates a throwaway database, analyses it against the security-extended suite, and prints every finding grouped by rule with its file and line. The scan is faithful to CI: it only flags a real source-to-sink taint flow, not a plain text match.

Trace what happens to the exit code. If the scan finds nothing, the command exits 0; if it finds something, it exits with the finding count. That makes it a gate for a pre-push hook:

tina4 codeql || { echo "CodeQL found something - fix it before you push"; exit 1; }

PHP is skipped. CodeQL doesn't support it, and CI scans PHP with Semgrep instead.

CodeQL options#

Creating the database is the slow part. The Actions, Ruby, and Python databases build in seconds, while a full JavaScript and TypeScript monorepo takes a few minutes. Run it before a push or on demand, not on every commit.

tina4 doctor reports whether the CodeQL client is installed and, when it is missing, prints the install command for your operating system.

Manage environment variables#

The client can list the variables that source code uses, generate .env.example, synchronize missing entries, and migrate legacy unprefixed names.

tina4 env --listtina4 env --exampletina4 env --synctina4 env --migrate

Migration creates .env.bak before it writes the canonical TINA4_* names. Use --yes to skip confirmation in CI.

Keep tools current#

tina4 updatetina4 skills alltina4 doctor

The update command refreshes the signed binary and installed Tina4 skills. The doctor command then shows which runtimes and framework clients are ready.

Remove the client#

When you are done with Tina4 the client will take itself back off the machine. tina4 uninstall first lists everything it put there: the config and credentials, the installed skills across Claude, Codex and Cursor, and the binary itself. Then it asks before it removes a single file.

tina4 uninstall            # lists targets, asks, then removestina4 uninstall --dry-run  # only reports what it would touchtina4 uninstall --yes      # skips the prompts, for scripts

The current project's own .tina4/, .tina4-metrics.json and .tina4-docs are offered as a separate, explicit opt-in. Nothing else on the filesystem is searched, so an uninstall never reaches into another project you forgot about.