Unolia Cli Laravel Package

Getting Started

Install globally (or run through cpx / drop the phar on PATH):

composer global require unolia/unolia-cli

Then authenticate and link the repository in one pass:

unolia login     # browser one-time code, like gh auth login
unolia init      # writes a committed .unolia/config.json
unolia deploy    # previews commits, asks, follows to completion

• Where to look first: run unolia bare to see the full noun/verb tree, and unolia help agents for the compact agent-oriented reference. The long-form command reference is in docs/cli on the repo.
• First use case: the deploy loop. init binds the directory to a team/project/website, deploy shows how far behind live the branch head and your checkout are, then follows the deployment. unolia watch lets you reattach later.
• For CI/agents: skip the browser with UNOLIA_TOKEN or unolia login --with-token. Don't rely on interactive prompts there — the tool is explicitly built to detect a pipe and switch to non-prompting structured output.
• MCP in one command: unolia mcp setup wires the Unolia MCP server into Claude Code, Cursor, VS Code, Codex, Gemini CLI, and others.

unolia status is the sanity check for why a command resolved to a given project — it reports which source answered (config file, flags, UNOLIA_* env, or git remote).

Implementation Patterns

Commit the context file, not the credentials. .unolia/config.json is meant to be committed and carries team/project/website binding, so every teammate and CI job gets correct scoping with zero flags. Keep tokens out of it — they live in ~/.config/unolia/hosts.json. Layer overrides via flags or UNOLIA_* variables when you need one command to target something else.

Deploy loop as the default workflow. unolia deploy (preview → confirm → follow), with unolia watch to reattach after a dropped connection. Ctrl+C cancels the local follow, not the remote work — the deployment keeps going, so watch is the recovery path rather than re-deploying.

DNS with a CI guardrail. dns export to capture the zone, dns check in a scheduled job to diff the declared zone against what resolvers actually answer (it prints only differences, which makes it alert-friendly). For changes, dns set / dns edit with --dry-run first, then --yes once the diff is what you expect; dns set follows propagation for you.

Issues as a triage-to-patch pipeline. issue list to see what's broken and fixable, then issue fix to preview a remediation and apply it. Preview-then-apply is the safe pattern here too.

Automations and CI. automation run | resume | replay | watch for long-running work; a run that stops on a question is answered in place rather than restarted. ci rerun / ci cancel cover the common failed-pipeline reactions.

Scripting and agent integration. Every command supports --json [fields], --jq, and --format table|json|ndjson|csv|yaml; everything that mutates supports --dry-run and --yes. Build internal tooling on structured output plus exit codes rather than parsing tables. Use unolia api (gh-api style) to reach endpoints with no first-class command — this is the extension point that keeps you from forking the CLI.

Local/production parity. configure herd writes herd.yml from production and runs herd init; compare local diffs your PHP, Laravel, and Composer versions against production. Pair these with open (project, website, live site, repo, or the site at its provider) to cut context-switching.

Gotchas and Tips

• Token migration is silent but real. A v1 token at ~/.unolia/cli/config.json is migrated to ~/.config/unolia/hosts.json (mode 0600) on first run; the old file is left untouched. Don't assume the old path is still the source of truth when debugging CI auth.
• UNOLIA_API_TOKEN still works, with a warning. Rename to UNOLIA_TOKEN now — the warning will end up in logs and, eventually, the variable will go away.
• v1 verbs are hidden, not removed. domain:list, domain:records, domain:add/update/remove/watch, dig, teams, me all still execute but won't appear in help. Existing scripts survive; new ones should use dns and team.
• The CLI now talks to /api/v2. Any script that calls the API directly via unolia api must move to v2 paths — this is the most likely silent breakage in a v1-to-v2 upgrade.
• Exit codes are the contract, not just "nonzero means bad". 7 means awaiting input (a valid state, answer it and resume), 130 is an expected interrupt, 5 is forbidden/plan-limit rather than a bug, 2 is usage. Branch on them appropriately instead of treating every nonzero as failure.
• --yes + --dry-run is a safety combination, not a default. Adding --yes to a mutating command in CI is fine only after the dry run has been reviewed; combine them deliberately.
• Scope failures are self-correcting. Auth errors name the exact unolia auth refresh --scopes <scope> to run — read the message rather than re-logging in from scratch.
• Colors and prompts follow NO_COLOR and CI. In pipelines you get no prompts and no color; don't write automation that depends on interactive confirmation. Prefer --json/--format ndjson for streaming parse-safe output and --jq if you don't want to assume a jq binary.
• unolia upgrade verifies the phar hash and updates in place — convenient, but if reproducibility matters in CI, download a pinned unolia.phar instead of letting the binary self-update.
• PHP 8.2+, unchanged from v1; check compare local before blaming the CLI for version drift.
• Review .unolia/config.json before committing the first time in an existing repo — it's designed to be shared, but confirm no environment-specific values leaked in.