Unolia Cli Laravel Package

Technical Evaluation

What this package actually is. Unolia CLI is not a library you composer require into a Laravel application. It is a globally installed developer/operations CLI (composer global require unolia/unolia-cli, cpx, or a unolia.phar on PATH) that drives app.unolia.com over /api/v2. There is no runtime coupling to the application codebase, no service provider, no config publish step, and no autoloaded classes in the app. From a TPM risk standpoint that is the decisive fact: the blast radius on production application builds is effectively zero.

Architecture fit. The tool sits in the developer-tooling and platform-operations layer: project/website linking, deployments, CI control, automations, DNS, providers, issues. That maps well onto a Laravel team that already treats the platform as the deploy target and wants the terminal and CI to be first-class rather than a browser tab. The committed .unolia/config.json is the interesting architectural decision — repo-scoped context (team, project, website) with documented precedence across flags, UNOLIA_* env vars, and git remote, plus unolia status to reveal which source won. That precedence model is the thing most likely to cause confusing behaviour in monorepos or multi-website repos and deserves a spike.

Integration feasibility. Straightforward in both interactive and non-interactive contexts. --json [fields], --jq, --format table|json|ndjson|csv|yaml, --dry-run, --yes, and a documented stable exit-code table (0 ok, 1 remote, 2 usage, 3 auth, 4 not found, 5 forbidden/plan, 6 timeout, 7 awaiting input, 130 interrupted) are exactly the primitives needed to wrap commands in CI and scripts. The explicit "never prompts in a pipe" contract removes the usual CLI-in-CI hang risk. unolia help agents is a low-cost way to give coding agents a correct command surface without writing our own instructions file.

Technical risk. Concentrated in a few areas rather than broadly distributed:

• API v2 migration is the real breaking change. The CLI now talks to /api/v2; any script using unolia api with v1 paths must be rewritten. This is the item that will bite quietly.
• Production-mutating commands from laptops. dns set, dns remove, issue fix, provider fix, --yes bypassing confirmation. These are governed by Unolia-side RBAC/scopes, not by the CLI — we need to confirm what that actually enforces.
• Self-updating binary. unolia upgrade replaces the phar in place and checks its hash. Convenient, but it means a developer machine or CI runner can silently change tool version mid-pipeline unless pinned.
• Tool mutates local developer configuration. unolia mcp setup writes MCP server entries into Claude Code, Cursor, VS Code, Codex, Gemini CLI, Junie, Kiro, OpenCode and Amp; configure herd writes herd.yml and runs herd init. Both are opinionated writes outside the repository.
• Token migration touches home directories. v1 token in ~/.unolia/cli/config.json is copied to ~/.config/unolia/hosts.json at mode 0600 on first run; the old file is left in place. The stale original staying behind is a minor hygiene issue worth noting in rollout comms.

Key questions for the vendor/platform owner:

1. What is the support window and deprecation policy for the hidden v1 verbs (domain:*, teams, me)? When do they go away?
2. Does .unolia/config.json ever contain anything sensitive, and what is the reviewed schema for committing it?
3. What scopes exist, how are they enforced server-side, and can DNS/issue fix mutations be restricted per role or per environment?
4. Rate limits, audit logging, and retention on /api/v2 — are CLI actions attributed to the individual token holder in the platform audit trail?
5. Windows/PowerShell support: shell completion is stated for bash, zsh, fish only. Is Windows a supported developer platform?
6. Is there a signed-release / verifiable-provenance story beyond the phar hash check, and can we pin versions deterministically in CI?
7. Does unolia mcp setup support a dry-run or a diff so we can review what it writes before it writes it?

Integration Approach

Stack fit. Clean. PHP 8.2+ matches any current Laravel 10/11/12 estate, and since the CLI is installed globally or via phar, it never enters composer.json and never touches the build graph. The only genuine stack question is whether composer global require is acceptable on managed developer images versus distributing a pinned phar — I would lean pinned phar for reproducibility and to make unolia upgrade a deliberate act rather than an ambient one.

Migration path. Low-effort but not zero-effort. Three steps: (1) first run auto-migrates the token, so interactive users need do nothing; (2) rename UNOLIA_API_TOKEN to UNOLIA_TOKEN in CI secrets — it still works but emits a warning, so this is a clean-up task, not a blocker; (3) audit anything calling unolia api and move it to v2 paths. Step 3 is the only one requiring real work and it requires discovery, so budget for a short inventory pass across CI configs and scripts.

Compatibility. v1 verb spellings continue to work, hidden from help, with new spellings under dns and team. That gives a comfortable overlap window. I would still treat the hidden verbs as unsupported in our own tooling and standardise new scripts on the v2 names immediately, so we are not writing code against a deliberately undocumented surface.

Sequencing.

1. Week 1 — inventory and pin. Enumerate scripts, CI jobs, and any unolia api usage. Decide the distribution method (pinned phar for CI, composer global for laptops) and pin it. Validate token scopes against what each pipeline genuinely needs; prefer narrow tokens over a shared broad one.
2. Week 2 — pilot. One team, one non-critical project. Exercise init, status, deploy, watch, and --json output in a CI job. Confirm exit codes 3/5/6/7 behave as documented under real failure conditions.
3. Week 3 — governance. Agree policy on committed .unolia/config.json, on --dry-run-first for DNS changes, and on whether configure herd / mcp setup are opt-in or permitted on managed images. Confirm platform-side RBAC covers DNS and issue remediation.
4. Week 4 — rollout. Update CI env var names, migrate unolia api callers to v2, publish an internal quickstart derived from unolia help agents and docs/cli, and retire the hidden v1 verbs from our own documentation.
5. Ongoing. Re-evaluate on each minor release; treat CLI major versions as requiring the same inventory pass.

Operational Impact

Maintenance. Very low. Nothing to patch in the application, no dependency graph to reconcile, no upgrade treadmill forced by Laravel releases. The maintenance burden is instead procedural: keeping the tool version pinned, keeping tokens scoped and rotated, and keeping our internal command documentation current as the CLI's noun/verb tree expands. Because v2 is a rewrite with a much larger surface than v1's DNS-only scope, expect the command tree to keep growing, which means onboarding docs will drift if unowned.

Support. Vendor support posture is undocumented in these notes — no SLA, LTS branch, or deprecation calendar is stated. For a tool that can mutate production DNS and trigger deployments, that is the single largest gap. Recommend assigning an internal owner and asking the vendor directly for a support and deprecation policy before broad rollout. Meanwhile, note that the v1→v2 rewrite is precedent for large jumps between majors; our assumption should be that v3 will be similarly disruptive.

Scaling. Scales fine in the dimension that matters — CI concurrency and script count. Each pipeline run is an independent authenticated client with no shared state beyond the token, so there is no fan-out bottleneck on our side. Two scaling caveats: (a) unolia watch holds a connection open for the duration of a deployment, CI run, or DNS propagation, so watch-heavy pipelines need job timeouts and a fallback to polling; (b) API rate limits under many parallel runners are unknown and should be load-tested before we put high-fan-out automation behind it.

Failure modes. The documented exit-code contract is the strongest operational feature here and should be wired directly into pipeline logic rather than parsed from text. Specific modes to plan for: exit 3 (auth) from expired or under-scoped tokens — in CI this should fail fast with a message pointing at unolia auth refresh --scopes, not retry; exit 5 (forbidden or plan) when a feature is gated, which is a human decision not a transient error; exit 6 (timeout) and exit 7 (awaiting input), the latter being the interesting one because an automation that pauses for a question will surface as exit 7 rather than a hung job — good, provided we treat 7 as "route to a human" rather than retry; exit 130 on interrupt with remote work continuing, which means a cancelled CI job may still leave a live remote operation and needs to be reconciled with watch. Non-CLI failure modes: unpinned upgrade changing behaviour mid-pipeline, a stale v1 token file left on disk at the old path, and .unolia/config.json pointing at the wrong website in a multi-site repo.

Ramp-up. Shallow for anyone who has used gh. The gh-shaped command tree, browser/one-time-code login, unolia init for repo context, and unolia status for provenance mean most developers will be productive in a single session. Two audiences need slightly different enablement: humans need a short internal quickstart plus the --dry-run habit for DNS; CI and agent authors need the exit-code table, --json/--jq field discovery, and unolia help agents folded into agent instructions. Budget roughly half a day of enablement per team and one deeper session for whoever owns the CI pipelines.