ttctl

# TTCtl

[![CI](https://github.com/alexey-pelykh/ttctl/actions/workflows/ci.yml/badge.svg)](https://github.com/alexey-pelykh/ttctl/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/ttctl?logo=npm)](https://www.npmjs.com/package/ttctl)
[![npm downloads](https://img.shields.io/npm/dm/ttctl?logo=npm)](https://www.npmjs.com/package/ttctl)
[![GitHub Repo stars](https://img.shields.io/github/stars/alexey-pelykh/ttctl?style=flat&logo=github)](https://github.com/alexey-pelykh/ttctl)
[![License](https://img.shields.io/github/license/alexey-pelykh/ttctl)](LICENSE)
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-3.0-4baaaa.svg)](CODE_OF_CONDUCT.md)

Personal-productivity CLI and MCP server for your own [Toptal Talent](https://talent.toptal.com) profile.

## ⚠️ Unofficial — Personal Use Only

**TTCtl is NOT affiliated with, endorsed by, or supported by Toptal LLC.** It is a personal-productivity tool that interacts with Toptal Talent's web/mobile interfaces using your own session, exclusively for your own profile's data.

This tool is built for **fair use** and shared in case it's useful to other Toptal talents who want similar tooling for their own profiles. It is **NOT** to be used for:

- Spam or unsolicited outreach to recruiters / clients
- Mass automation of job applications, profile updates, or messaging
- Engagement-signal manipulation, application bombing, recruiter scraping
- Operating against profiles that aren't your own
- Any behavior that violates [Toptal's Terms of Service](https://www.toptal.com/tos) or burdens the platform

If you encounter misuse of TTCtl, please see [Abuse reporting in SECURITY.md](SECURITY.md#abuse-reporting).

Architectural friction in the codebase (sequential rate limits, single-credential design, no batch parallelism on automation-prone endpoints) is intentional. Don't remove it.

"Toptal" is a trademark of Toptal LLC. The name appears in this project's description as **nominative fair use** only — TTCtl is not a Toptal brand.

## What It Does

TTCtl gives you (and your AI assistants, via [MCP](https://modelcontextprotocol.io)) programmatic access to your own Toptal Talent profile:

- **Profile** — view and update your talent profile (basic info, skills, employment, education, certifications, industries, portfolio, visas, resume, external links, reviews, photo)
- **Applications** — review your activity items (applications, availability requests, interviews, engagement signals); per-status-group counts via `applications stats`; confirm / reject open Interest Requests via `applications confirm` / `applications reject`; fetch interview detail (interviewer with TopChat thread handle, client-side contact, scheduled slot, agenda link, prep-guide ref) via `applications interview show <id>`; read your interview prep notes via `applications interview notes show <jobId>`; fetch availability-request detail (status, kind, recruiter Fixed rate, comment, lifecycle timestamps, job) via `applications availability-request show <id>`
- **Engagements** — view current and past engagements; manage engagement breaks; per-status counts via `engagements stats`
- **Jobs** — browse opportunities (incl. the algorithmic `jobs recommended` feed, the per-job `jobs match-quality` match-score breakdown, and the per-job `jobs rate-insight` rate-intelligence panel); manage saved / viewed / not-interested signals; configure search subscription; direct-apply via `jobs apply <id> --consent` (legal-compliance gate is mandatory). Add `--suggest-answers` to fetch your own historical answers to similar prior questions as advisory autocomplete suggestions (opt-in, off the critical apply path; failures degrade gracefully). The MCP tool `ttctl_jobs_apply_similar_answers` exposes the same surface to agents.
- **Timesheets** — list, view, update, and submit timesheet billing cycles
- **Availability** — view and update working hours and allocated weekly hours
- **Contracts** — view talent-level contracts (Toptal Direct, MSA, etc.)
- **Payments** — view payout history, aggregate payment totals (`payments summary`), and payment methods; show current hourly rate via `payments rate current` (lightweight) or the unified `payments rate show` projection; submit rate-change requests
- **Surveys** — list pending surveys, submit structured answers, and add free-text feedback on post-interview / NPS prompts; submissions and feedback are irreversible and consent-gated
- **Auth** — bootstrap config, sign in, check status, sign out

Surfaces are gated to read-heavy / personal use. Operations that would enable mass automation against the platform are deliberately not exposed.

### Out of scope

The following Toptal Talent surfaces are out of scope **by design** — they enable abuse (mass-automation or spam vectors), require third-party SDKs TTCtl doesn't depend on, target client-onboarding rather than the talent-side workflow, belong to staff- or sourcing-side workflows, or are one-time / mobile-only UI affordances with no recurring CLI value:

- **Notification preferences** — `UpdateJobAlertSettings`, `UpdateSmsNotificationsSettings`, `UpdateTimesheetReminderSettings`, `UpdateNotificationSetting` (abuse-prevention — silencing alerts is a precursor to other abuse)
- **Community / Slack interaction** — events, channels, messages, RSVP (third-party-SDK — community participation is human-side, not CLI-side)
- **Referral flow** — send referral, claim reward, track referrer (abuse-prevention — programmatic referral generation is a spam vector)
- **Become-client / consultations / coaching / gigs** — buyer-side workflows (client-onboarding — not talent-side profile management)
- **Hire-me-page publishing** — public marketing page (one-time-action — not recurring profile state)
- **Video pitches / Zendesk integration** — Ziggeo/CameraTag- and Zendesk-backed surfaces (third-party-SDK — not part of the GraphQL surface TTCtl targets)
- **TopChat messaging surface** — messages and file downloads remain out of scope; only the per-interviewer discovery handle is surfaced via `applications interview show` (full surface tracked in #23)
- **Mobile-only widgets** — Story, MobileTopTip, MarketCondition (mobile-only-UI — no CLI equivalent value)
- **Quizzes / questionnaires** — onboarding-terminal forms (one-time-action — not recurring profile state)
- **Staff-side workflows** — `SEND_CONTRACTS`, testimonial publishing, snapshot history (staff-side — Toptal-staff surfaces, not talent-side)
- **Talent-signal sourcing** — `CreateTalentSignal`, `GetTalentSignalSetup` (sourcing-side — recruiter / staff identifying talent, not talent-side)

> **Note**: The `scheduler.toptal.com` surface (interview scheduling) is currently absent rather than out by design — deferred until reverse-engineering research closes.

See [What It Does](#what-it-does) above for the positive scope.

## Prerequisites

- **Node.js** >= 22.19.0
- A **Toptal Talent** profile (you must be a Toptal talent to use this — it has no value to anyone else)
- Recommended: **[1Password CLI](https://developer.1password.com/docs/cli/get-started/)** (`op`) for credential resolution

### Supported platforms

TTCtl uses [`node-wreq`](https://www.npmjs.com/package/node-wreq) for Chrome
TLS-fingerprint impersonation on the Cloudflare-protected surfaces (profile
editing). That transport ships as a prebuilt native binary, available for:

| OS      | Architecture           | libc          | Supported  |
| ------- | ---------------------- | ------------- | ---------- |
| macOS   | x64 (Intel)            | —             | ✅         |
| macOS   | arm64 (Apple Silicon)  | —             | ✅         |
| Linux   | x64                    | glibc         | ✅         |
| Linux   | x64                    | musl (Alpine) | ✅         |
| Linux   | arm64                  | glibc         | ✅         |
| Linux   | arm64                  | musl (Alpine) | ❌ not yet |
| Windows | x64                    | —             | ✅         |
| Windows | arm64 (Windows on ARM) | —             | ❌ not yet |

On an unsupported platform, `npm install -g ttctl` still **succeeds** (the
native binary is an optional dependency) and mobile-gateway commands keep
working — but any Cloudflare-protected command (anything that edits your
profile) fails with a clear `NATIVE_MODULE_UNAVAILABLE` error naming your
platform and this supported set. If you need one of the two not-yet-supported
targets, please [open an issue](https://github.com/alexey-pelykh/ttctl/issues).

## Installation

```sh
npm install -g ttctl
```

Or run directly with npx:

```sh
npx ttctl --help
```

### Hardened install (recommended)

For maximum supply-chain safety, install with `postinstall` hooks disabled:

```sh
npm install -g --ignore-scripts ttctl
```

`--ignore-scripts` blocks `preinstall` / `postinstall` / `prepare` hooks
across the entire dependency tree at install time. This prevents a
compromised transitive dep (PhantomRaven, Shai-Hulud, etc.) from
executing code on your machine during install — closing the
most-exploited supply-chain attack vector against package-manager users.

TTCtl itself ships no install-time hooks. Disabling them is purely a
defense against malicious behavior in dependencies you don't directly
control. See [SECURITY § User-install supply-chain hardening](SECURITY.md#user-install-supply-chain-hardening).

## Quick Start

```sh
# 1. Install
npm install -g ttctl

# 2. Bootstrap a config interactively (recommended)
#    Walks you through Form A (1Password reference; vault + item picker
#    when the `op` CLI is installed) or Form B (literal credentials,
#    explicit warning). Output: ~/.ttctl.yaml at mode 0600.
ttctl auth init

# 3. Sign in (captures the bearer back into ~/.ttctl.yaml under auth.token)
ttctl auth signin

# 4. Verify
ttctl auth status

# 5. View your profile
ttctl profile show
```

> **`ttctl auth init`** scaffolds a fresh `~/.ttctl.yaml` interactively. Choose Form A (1Password reference, recomme