There There Cli Laravel Package

Technical Evaluation

Classification is the first decision. spatie/there-there-cli is not a package we require and use inside application code. It is a Laravel Zero standalone CLI shipped as a committed PHAR (builds/there-there), installed via composer global require, with one command per There There API endpoint generated from a bundled OpenAPI spec through spatie/laravel-openapi-cli. It competes with, rather than substitutes for, an in-app integration layer. Any roadmap item phrased as "integrate There There into our Laravel app" must be split into ops automation (this package qualifies) and runtime integration (it does not — that still requires our own HTTP client, retries, typed DTOs, and queued workers).

Architecture fit. The only viable pattern is shell-out: Laravel console commands, the scheduler, and CI jobs invoke there-there via Symfony\Component\Process\Process, parse JSON from stdout, and treat non-zero exit codes as failures. This fits well for reporting digests, SLA sweeps, escalation routing, bulk status/tag remediation, and on-call triage. It does not fit request-path work: every invocation is a fresh process with Composer-global binary resolution, no connection reuse, and no shared retry/backoff layer.

Strengths that materially reduce scope:

• Broad, spec-synchronised command surface (tickets, messages, notes, forwards, tags, teams, members, contacts, saved views, workflows, attachments).
• First-class multi-workspace profiles with per-invocation --profile and an X-Workspace-Id header (0.5.0). Multi-brand automation becomes a supported shape rather than bespoke token juggling.
• JSON output across commands, so scripting needs no HTML or log scraping.
• Improving security posture: 0600 on ~/.there-there/config.json, TLS verification on by default since 0.5.0 (relaxed only for localhost/127.0.0.1/*.test).
• Ships an agent skill (there-there install-skill), relevant if we expect coding agents or on-call engineers to drive triage from a terminal.

Technical risk, ordered by blast radius:

1. Wrong-workspace mutation. Profiles are a convenience and a hazard. Any script relying on the default profile will mutate whichever workspace was last used. Mitigation: make --profile mandatory and asserted in every wrapper, never rely on ambient state.
2. PHAR/spec drift. The binary in builds/ is what Composer installs and nothing rebuilds it automatically. 0.8.0 was tagged on a spec resync but shipped the 0.7.1 PHAR, so show-ticket was absent and stale get-tickets-ticket remained. Version numbers therefore do not reliably predict command surface. Mitigation: pin an exact version and run a smoke test asserting --version plus a known command set before any rollout.
3. Pre-1.0 churn. Command names are derived from spec operationIds and have already been renamed (get-tickets-ticket → show-ticket, patch-company → update-company). Scripts authored against one version break on upgrade. Mitigation: pin, and contract-test the command surface in CI.
4. Credential handling in CI. Tokens live on disk at ~/.there-there/config.json (0600). Shared runners imply tokens at rest on a host. No documented environment-variable token injection — a blocking question.
5. Output contract edge cases. 0.8.2 fixed download-attachment corrupting non-JSON bodies; the framing line, trailing newline, and console formatter eating <...> bytes were upstream defects. Any parser must tolerate binary passthrough and should not assume stdout is always JSON. Whether errors go to stderr is unconfirmed.
6. Undocumented pagination and rate limits. list-tickets is "paginated" but cursor/limit semantics and API throttling are not documented in the README. Bulk remediation as an N-process loop against an unknown quota is a real risk.
7. Ecosystem validation is nil. 0 stars, 0 dependents, 0.x versions. Vendor reputation (Spatie) and MIT licensing offset this somewhat, but there is no community blast radius absorbing our bugs.

Key questions for the vendor/owner before commitment:

• Can the API token be sourced from an environment variable or stdin rather than the on-disk profile store, for CI use?
• What are the pagination parameters and rate limits per endpoint, and what status/body shape does the CLI emit on 429?
• Are exit codes distinct per failure class (auth, validation, throttle, transport), or binary 0/1?
• Is the PHAR reproducible from a tagged commit, and is there a CI check preventing a stale PHAR from shipping again?
• Does the CLI write tokens anywhere besides ~/.there-there/config.json, and is there a documented rotation procedure?

Integration Approach

Stack fit. Laravel scheduler + console commands wrapping Process is the natural home. No service provider, no facade, no queue integration — the package sits outside the app container. That is an advantage for blast-radius containment and a disadvantage for observability: no shared HTTP middleware means our logging, tracing, and retry semantics must be layered in the wrapper.

Migration path. Treat as greenfield ops tooling, not a port. There is nothing to migrate from; the decision is whether to build direct API clients versus adopting this binary. For read-heavy reporting and ad-hoc triage, the CLI wins on time-to-value (days, not sprints). For anything needing typed models, transactional retries, or per-request tracing, build the client — do not bend the CLI into that shape.

Compatibility. Require PHP and Composer available on every execution host, including CI images. Pin spatie/there-there-cli:0.8.2 (or newer verified build) explicitly; composer global require has no per-project lockfile, so pinning must be baked into the base image and asserted at boot. Verify the global Composer bin dir is on PATH in non-interactive shells — a classic silent failure in cron and CI contexts. Pin the profile name in every call site; do not depend on there-there use.

Sequencing (each stage gated):

1. Read-only pilot. get-me, list-tickets, show-ticket, list-ticket-activities against one workspace from a single engineer's machine. Confirm JSON shape stability and pagination behaviour. Gate: documented response schema and confirmed pagination flags.
2. CI smoke contract. Nightly job asserting binary version, command presence for the commands we depend on, and a single read call succeeding. Gate: alerting on drift.
3. Scheduled read automation. SLA digest / backlog report into Slack or email. Gate: two weeks of clean runs, no auth failures.
4. Mutations, narrow scope. add-note-to-ticket, update-ticket-status with explicit --profile and a dry-run flag in our wrapper. Gate: peer review of every mutating call site and an audit log of what the CLI changed.
5. Bulk remediation. Only after rate limits are characterised; add jitter, backoff, and a per-run cap.
6. Agent enablement. Roll out install-skill only with a read-only scoped token and a documented prohibition on mutating commands.

Operational Impact

Maintenance. Two maintenance streams: the vendor's, which we do not control, and ours, which is the wrapper layer. Budget roughly one engineer-day per quarter for version review plus the cost of each upgrade's contract test. The 0.x line guarantees at least occasional breaking renames; assume one breaking upgrade per year. The stale-PHAR class of bug means we must independently verify behaviour post-install rather than trusting the changelog.

Support. MIT-licensed open source with no vendor SLA. There is no support contract to escalate to; issues surface as GitHub issues with no committed response time. Internal support burden is a runbook covering authentication, profile switching, token rotation, and the upgrade procedure — realistically half a day to write, and it must be written before the second engineer touches the tool.

Scaling. Scales linearly with invocation count, and invocation count is the cost unit: one process spawn plus one TLS handshake per API call. Fine for tens to low hundreds of calls per run; a full-backlog sweep of thousands of tickets becomes minutes of wall clock and a rate-limit hazard. There is no batching, no connection pooling, and no concurrency primitive — parallelism must come from our side, which then multiplies the rate-limit exposure. Realistic ceiling: single-workspace reporting and per-ticket operations, not bulk re-processing.

Failure modes and detection:

The critical property is that failures must be loud. A wrapper that swallows non-zero exits or treats empty stdout as "no tickets" converts an outage into silent inaction on SLA breaches — that is the scenario worth designing against first.

Ramp-up. Low. An engineer familiar with CLIs and JSON is productive in under an hour; the skill file is a usable onboarding artifact in its own right. The non-obvious cost is guardrail education, not syntax: engineers must internalise that the default profile is ambient state, that version numbers do not imply command surface, and that mutating commands have no dry-run. Budget a short team walkthrough before the first mutation stage, and gate it on the runbook being written.