Ttctl

TTCtl

Personal-productivity CLI and MCP server for your own Toptal Talent 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 or burdens the platform

If you encounter misuse of TTCtl, please see Abuse reporting in SECURITY.md.

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) 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 ; read your interview prep notes via applications interview notes show ; fetch availability-request detail (status, kind, recruiter Fixed rate, comment, lifecycle timestamps, job) via applications availability-request show
• 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 --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 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 for Chrome TLS-fingerprint impersonation on the Cloudflare-protected surfaces (profile editing). That transport ships as a prebuilt native binary, available for:

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.

Installation

npm install -g ttctl

Or run directly with npx:

npx ttctl --help

Hardened install (recommended)

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

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.

Quick Start

# 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, recommended) or Form B (literal credentials, discouraged — guarded by an explicit warning). On Form A with the op CLI installed, a vault picker and a LOGIN-category item picker run. Without op or on JSON-shape failure, the prompt falls back to a freeform op://VAULT/ITEM reference. The output file is written atomically at mode 0600 and refuses to overwrite an existing file unless --force is passed. The command is interactive only — pipe stdin or a non-TTY context exits non-zero with a clear message.

`ttctl auth signin` runs the EmailPasswordSignIn GraphQL mutation, captures the session bearer, and writes it BACK into the same ~/.ttctl.yaml file under auth.token (atomic write; comments preserved; mode 0600). All subsequent commands replay it as Authorization: Token token= on every GraphQL request. The op CLI is invoked only at signin time to resolve your credentials. There is no separate token file — your config and your live session live in one YAML.

Hand-authoring the config also works (drop a YAML file at ~/.ttctl.yaml, chmod 600); see the Configuration section below for the four valid auth shapes. ttctl auth init is the recommended starting point.

Configuration

TTCtl uses a single config file — no profiles. The config-file path is resolved deterministically (highest precedence wins):

1. --config flag — explicit override (per-invocation).
2. TTCTL_CONFIG_FILE env var — process-scoped (CI, direnv).
3. ~/.ttctl.yaml — POSIX home dotfile (only fallback).

XDG paths ($XDG_CONFIG_HOME/ttctl/config.yaml, ~/.config/ttctl/config.yaml) and the current-working-directory ./.ttctl.yaml are not auto-discovered. To use a project-local config, point TTCTL_CONFIG_FILE at it via direnv:

# .envrc in your project root (requires `direnv` installed and `direnv allow` run)

export TTCTL_CONFIG_FILE="$PWD/.ttctl.yaml"

Sync-root exclusion

TTCtl refuses to persist the captur