PHPackages                             tutamen/cli - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [CLI & Console](/categories/cli)
4. /
5. tutamen/cli

ActiveLibrary[CLI & Console](/categories/cli)

tutamen/cli
===========

Tutamen CLI — scan your Laravel working tree for security issues before you push

v0.3.0(2w ago)04↑50%MITPHPPHP ^8.3

Since Jun 14Pushed 6d agoCompare

[ Source](https://github.com/Arctic-Works/tutamen-cli)[ Packagist](https://packagist.org/packages/tutamen/cli)[ Docs](https://tutamen.io)[ RSS](/packages/tutamen-cli/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (11)Versions (4)Used By (0)

Tutamen CLI
===========

[](#tutamen-cli)

Scan your Laravel working tree for security issues **before you push**.

`tutamen` snapshots your local code, uploads it to [Tutamen](https://tutamen.io), and the server runs the same sandboxed scanners as a repository scan — secrets (gitleaks), dependency CVEs (composer audit), SAST (opengrep) and Laravel-aware AST rules. Results are returned to you with a meaningful exit code, so a pre-push git hook can block risky pushes. Nothing is scanned locally and no rule binaries are distributed — there is nothing to keep up to date but this package.

Requirements
------------

[](#requirements)

- PHP 8.3+
- `git` and `tar` on your `PATH`
- A Tutamen account and an API token (Settings → API tokens)

Install
-------

[](#install)

```
composer global require tutamen/cli
```

Make sure Composer's global bin directory is on your `PATH` (typically `~/.composer/vendor/bin` or `~/.config/composer/vendor/bin`). Then:

```
tutamen --version
```

Authenticate
------------

[](#authenticate)

Create an org-scoped token in the dashboard under **Settings → API tokens**(it is shown once), then:

```
tutamen auth --server=https://app.tutamen.io
# paste your token when prompted (input is hidden)

tutamen auth:status   # show the server and a masked token
tutamen auth:logout   # forget stored credentials
```

The CLI verifies the token against the selected server before saving it. Non-local servers must use HTTPS. Credentials are stored in `~/.config/tutamen/config.json` with `0600`permissions. This file is personal — never commit it. The committed `.tutamen.json` (below) holds hook settings only and must never contain a token; the CLI refuses to read it if it looks like it does.

Scan
----

[](#scan)

From anywhere inside your repository:

```
tutamen scan                      # tracked + locally-modified files
tutamen scan --include-untracked  # also untracked, non-ignored files
tutamen scan --fail-on=high       # only fail on high/critical findings
tutamen scan --json               # machine-readable envelope
tutamen scan --agent              # one JSON envelope for an AI agent (see below)
tutamen scan --agent --verification # mark a reviewed fix re-scan as verification
```

The snapshot includes your tracked files at their **current** working-tree content (so a secret you just edited but have not committed is still caught) and excludes anything git ignores — `vendor/`, `node_modules/` and `.git/` are never uploaded. Results are ephemeral: they are returned to you and never merged into your repository's dashboard findings.

### Fix with your own AI (`--agent`)

[](#fix-with-your-own-ai---agent)

`tutamen scan --agent` emits a single JSON envelope an AI agent can act on:

```
{
  "envelope_version": 2,
  "prompt_version": 2,
  "prompt": "…server-managed instructions for the agent…",
  "scan": { "id": "…", "status": "completed", "stats": { … } },
  "findings": [ { "rule_id": "…", "untrusted_location": { … }, "fix_md": "…" } ]
}
```

The `prompt` is fetched from the server (and cached locally for 5 minutes), so the behaviour an agent follows improves server-side without a CLI release. Each finding carries its trusted rule `fix_md` remediation guidance and an explicitly untrusted location. Source snippets and scanner messages are excluded from the agent envelope so repository content cannot become trusted instructions. The agent reads findings and proposes local edits on **your** AI subscription; it must wait for your approval and show the local diff before verification. Your code never goes to a third-party model by us.

If a token is revoked or expires, requests fail immediately. Create a named replacement in **Settings → Access tokens** and run `tutamen auth` again; the verified replacement overwrites the old local credential.

### Install the agent skill

[](#install-the-agent-skill)

The `tutamen-security` skill ships with this CLI. It tells your agent to run `tutamen scan --agent`, then follow the server-managed prompt in the output. Install it into your agent's skills directory:

```
tutamen skill:install                 # both Claude Code & Codex, this project
tutamen skill:install --global        # both, for all projects (in your home dir)
tutamen skill:install --agent=claude  # only Claude Code (.claude/skills)
tutamen skill:install --agent=codex   # only Codex CLI (.codex/skills)
tutamen skill:install --print         # print SKILL.md to stdout (any other agent)
```

By default it installs for **both** Claude Code (`.claude/skills`) and Codex (`.codex/skills`); pass `--agent` to target just one. Both auto-discover the skill, so just ask your agent to "scan this repo for security issues". Re-running `tutamen skill:install` after a `composer global update tutamen/cli`refreshes the installed skill.

### Exit codes

[](#exit-codes)

CodeMeaning`0`Clean — no findings at or above your threshold`1`Findings at or above the threshold (the push is blocked when run from a hook)`2`The scan could not run (not authenticated, network error, server error)The threshold is set with `--fail-on=critical|high|medium|low|any` (default `any`) or in `.tutamen.json`. An explicit flag always wins.

Pre-push hooks
--------------

[](#pre-push-hooks)

```
tutamen hooks:install                                   # native .git/hooks/pre-push
tutamen hooks:install --husky                           # .husky/pre-push instead
tutamen hooks:install --branches='^(main|release/.*)$' --fail-on=high
tutamen hooks:uninstall                                 # remove the tutamen hook
```

`--branches` and `--fail-on` are written into a committed `.tutamen.json` so your whole team shares them:

```
{
  "hooks": {
    "branches": "^(main|release/.*)$",
    "failOn": "high"
  }
}
```

The hook only scans branches matching `branches` (omit it to scan every branch). It is installed as a clearly marked block, so an existing hook is appended to — never clobbered — and `hooks:uninstall` removes only Tutamen's part. A blocked push shows the findings and reminds you that `git push --no-verify` bypasses the hook once.

Continuous integration
----------------------

[](#continuous-integration)

The exit codes make `tutamen scan` usable in any CI pipeline without a dedicated integration:

```
tutamen scan --server="$TUTAMEN_SERVER" --token="$TUTAMEN_TOKEN" --fail-on=high
```

License
-------

[](#license)

MIT © Arctic Works. See [LICENSE](LICENSE).

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance99

Actively maintained with recent releases

Popularity5

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity41

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~16 days

Total

3

Last Release

14d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/1279c283054fb742ffd97da3ce0b010841d672461e07554fe7cf5420913c262d?d=identicon)[koenschipper](/maintainers/koenschipper)

---

Top Contributors

[![koen-schipper](https://avatars.githubusercontent.com/u/56150397?v=4)](https://github.com/koen-schipper "koen-schipper (13 commits)")

---

Tags

clilaravelstatic analysissecuritysecretspre-pushgit hookSAST

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/tutamen-cli/health.svg)

```
[![Health](https://phpackages.com/badges/tutamen-cli/health.svg)](https://phpackages.com/packages/tutamen-cli)
```

###  Alternatives

[laravel/framework

The Laravel Framework.

34.8k543.8M20.6k](/packages/laravel-framework)[drupal/core

Drupal is an open source content management platform powering millions of websites and applications.

19566.0M1.8k](/packages/drupal-core)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

585.6M607](/packages/shopware-core)[shopware/platform

The Shopware e-commerce core

3.4k1.5M3](/packages/shopware-platform)[typo3/cms

TYPO3 CMS is a free open source Content Management Framework initially created by Kasper Skaarhoj and licensed under GNU/GPL.

1.2k1.9M122](/packages/typo3-cms)[eslazarev/wildberries-sdk

Wildberries OpenAPI clients (generated).

293.1k](/packages/eslazarev-wildberries-sdk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)