Unolia Cli Laravel Package

Product Decisions This Supports

• Build vs. buy on internal platform tooling. If your team has hand-rolled shell scripts wrapping the Unolia API for deploys, DNS edits, or CI reruns, v2 replaces that maintenance burden: --json [fields], --jq, stable exit codes (0–7, 130), --dry-run, and --yes mean your scripts stop parsing human-readable output and stop inventing their own failure semantics.
• Release cadence and change-safety policy. unolia deploy previews the commit delta between live, branch head, and local checkout before asking, then follows to completion; unolia watch detaches with Ctrl+C leaving remote work running. This is the substrate for deciding how often you ship and what "safe deploy" means procedurally.
• Self-serve diagnostics vs. support headcount. unolia status (names which source resolved the context), dns check (prints only the diff between zone and resolver answers), and compare local (PHP/Laravel/Composer versions vs. production) map directly to recurring ticket categories — drift, misconfiguration, environment mismatch. Each of these is a decision point: invest in automation or keep paying humans to triage.
• DNS-as-reviewed-configuration. dns list/add/set/edit/remove/watch/dig/check/export scoped to the project zone, combined with --dry-run, supports a governance decision to require a reviewable, reversible DNS change process instead of console clicking.
• Maintenance/remediation roadmap. issue list → preview fix → apply, plus automations run/resume/replay (including answering a run that paused on a question, in place) implies a product direction toward guided self-healing. Usable as evidence for a roadmap item on automated remediation, and as a ceiling on how much you build in-house.
• Credential and access model. Browser login with a one-time code scoped like gh auth login, scope-missing errors that name the exact unolia auth refresh --scopes <scope> command, UNOLIA_TOKEN for scripts, config at mode 0600. This supports a decision to put CLI access into CI without minting broad, long-lived tokens.
• Standardizing on one integration surface. unolia api (like gh api) is the escape hatch for endpoints without a first-class command. That removes the "we need a bespoke client for the one thing the CLI doesn't do" objection — a real build-vs-buy lever.
• Onboarding and environment parity. Committed .unolia/config.json via unolia init, plus configure herd (writes herd.yml from production, runs herd init) and open (jump to project/site/repo/provider). Directly supports a decision to shrink time-to-first-deploy for new engineers.
• Agentic tooling investment. unolia mcp setup registers the Unolia MCP server in Claude Code, Cursor, VS Code, Codex, Gemini CLI, Junie, Kiro, OpenCode, and Amp in one command; unolia help agents prints a short agent-facing contract; --format table|json|ndjson|csv|yaml on every command. This is the decision input for whether to let agents drive deploys/DNS, and under what guardrails.
• Deprecation timeline for internal v1 automation. v2 talks to /api/v2; v1 commands (domain:*, dig, teams, me) still work but are hidden from help; UNOLIA_API_TOKEN still works with a warning. Hidden-and-working is the classic pre-removal posture — treat this as a forcing function to schedule the rewrite of anything you built against v1.

When to Consider This Package

Consider it when:

• The team runs on Unolia (app.unolia.com). This is the control-plane client — outside that platform it has no function. It is a CLI distributed via Composer, not an embeddable PHP library; your integration surface is the shell, in dev and in CI.
• Deploys, DNS, CI runs, automations, and issues are already daily work and are currently spread across a web UI, ad-hoc scripts, and provider consoles; consolidating them into one command tree reduces context switching.
• You want automation and humans to use the same tool. The dual-mode contract (prompts and tables at a TTY; no prompts, JSON, meaningful exit codes in a pipe) is the specific reason to pick this over an API wrapper.
• You are evaluating agent-driven operations. unolia mcp setup, --format ndjson, --dry-run, and stable exit codes give an agent a bounded, inspectable action space — a prerequisite for letting one touch production at all.
• You want DNS changes to be diffable and reviewable (dns check, dns export, --dry-run) rather than imperative.
• Environment parity matters: compare local and configure herd are cheap wins for the "works on my machine" class of bug.
• You are on PHP 8.2+ with Composer available, or can drop the unolia.phar on PATH, or run cpx unolia/unolia-cli with no global install.
• You want repository-anchored context (.unolia/config.json committed) so commands need no flags, with flags, UNOLIA_* variables, and the git remote as fallbacks.

Look elsewhere when:

• You are not on Unolia. No amount of CLI polish makes this relevant.
• You need in-process PHP integration — an SDK or direct HTTP calls to /api/v2 is the right answer, not shelling out from a Laravel service.
• You require a vendor-neutral, multi-provider DNS story; this namespace is scoped to the Unolia-managed zone.
• You cannot commit .unolia/config.json (e.g., policy forbids repo-level environment metadata) and cannot supply UNOLIA_* variables everywhere — you lose the main ergonomic benefit.
• Your access model depends on role-based restrictions the CLI token scopes don't yet express; verify scope coverage before committing.
• You need long-term stability on the v1 spellings. They are hidden from help and the CLI now speaks /api/v2; plan for removal.
• You need a GUI-first workflow for non-terminal stakeholders — this is not that product, and open only partially bridges it.

How to Pitch It (Stakeholders)

For executives — one paragraph. Unolia's entire platform — projects, websites, deployments, CI, automations, DNS, providers — is now drivable from a single command line, with the same tool serving both engineers and automation. That means we stop maintaining glue scripts, we get an auditable and reversible record of infrastructure changes, and we can put the platform into our CI and agent workflows without building a bespoke integration. The upgrade is a rewrite, but tokens migrate automatically and old commands keep working, so the switching cost is a short, schedulable sweep rather than a migration project.

For engineering — why it's worth the afternoon. Login is browser-based with scoped tokens, so no more pasting long-lived credentials around; UNOLIA_TOKEN covers CI, and a missing scope tells you the exact auth refresh command to run. Every command supports --json/--jq/--format and a documented exit-code table, so scripts never parse prose and failures are branchable. --dry-run exists on anything mutating. unolia init commits repo context so commands work flag-free, and unolia status tells you which source answered when they don't. unolia api is the escape hatch for anything not yet wrapped, and unolia mcp setup wires the MCP server into the agent tooling in one command.

Risks and the ask. Three things to schedule, not discover: direct API callers must move to /api/v2 paths; UNOLIA_API_TOKEN should be renamed to UNOLIA_TOKEN (works today, warns, will presumably stop); v1 command spellings are hidden and should be treated as deprecated. Ask: pilot on one or two repositories, instrument deploy lead time and DNS-change error rate before and after, confirm CLI token scopes cover our access policy, then standardize in CI and retire the in-house scripts.