The Posting Tool
Friendly setup · start here

Setup guide

Follow these steps once. Short sentences. One action at a time. This covers the supported platforms: X, Threads, TikTok, Pinterest, YouTube, and Instagram.

Mac is the main path below. Windows and Linux notes are called out where paths differ. If you want extra technical detail later, open INSTALL.md in your project folder.

Use AI to help you set up

This is the fastest way to get set up. You also make fewer mistakes.

Paste this guide (or SETUP.md from your project folder) into ChatGPT, Claude, or Grok. Let the AI walk you one step at a time. If the AI gets stuck, open a GitHub Issue.

How

  1. Open ChatGPT, Claude, or Grok.
  2. Attach or paste this Setup guide (or SETUP.md from your project folder).
  3. Paste the prompt below.
  4. Do each step. Stop at every You should see… checkpoint. Tell the AI what you saw before it continues.

Copy this prompt:

I'm setting up Posting Tool on my computer. Walk me through SETUP.md one step at a time. Do not skip checkpoints. Wait for me to confirm each step before going to the next.

I'm on a Mac (tell me if Windows/Linux is different).
Platforms I'm using: [list them — X, Threads, TikTok, Pinterest, YouTube, Instagram as needed].
The project folder is: [paste path after I clone it].

Rules:
- Never invent commands that aren't in SETUP.md or the repo.
- If something looks like a secret (tokens, passwords), tell me not to paste it into chat.
- If a step fails, help me use the Troubleshooting section before guessing.
- If I'm using Instagram, TikTok, or Pinterest: stop until I confirm TikTok and Pinterest are Business, and Instagram is Business or Creator (not Personal). For Instagram: if the account is already Professional and the Schedule content switch is missing, keep going. The tool still posts. It publishes now instead of scheduling a time.
Do not paste secrets. Never paste passwords, cookies, or token files into the AI. If a file looks secret, tell the AI you have it — do not paste the contents.

Still do the checkpoints in this guide. If the AI skips a “You should see…” line, stop and do it anyway.

When something fails — use AI to fix it

Paste this guide (or SETUP.md) plus the error into ChatGPT, Claude, or Grok.

Give the AI:

  1. This Setup guide (or SETUP.md from your project folder).
  2. The error text from Terminal (the red lines / traceback).
  3. What you see in failed/ (paste the receipt text, or describe the filename).
  4. What you see in logs/screenshots/ — describe the screenshot (login wall, missing button, error banner). Do not upload screenshots that show passwords, cookies, tokens, or other secrets.

Copy this prompt:

Something failed while setting up Posting Tool. Help me fix it using SETUP.md.

Platforms I'm using: [list them — X, Threads, TikTok, Pinterest, YouTube, Instagram as needed].
The project folder is: [path].

Error text:
[paste the Terminal error]

What I see in failed/:
[paste receipt text or describe]

What I see in logs/screenshots/:
[describe the screenshot — do not upload secrets]

Rules:
- Never invent commands that aren't in SETUP.md or the repo.
- Do not ask me for passwords, cookies, or tokens. If a file looks secret, tell me not to paste it.
- Use the Troubleshooting section in SETUP.md first, before guessing.
- If I'm using Instagram, TikTok, or Pinterest: confirm TikTok and Pinterest are Business, and Instagram is Business or Creator (not Personal). For Instagram: if the account is already Professional and the Schedule content switch is missing, keep going. The tool still posts. It publishes now instead of scheduling a time.

Try the AI install prompt and this AI fix prompt first. If you are still stuck, open a GitHub Issue.

A. Before you start

Check these off first:

  1. Use a Mac if you can (easiest). Windows and Linux work too.
  2. Create (or already have) login accounts for the platforms you use: X, Threads, TikTok, Pinterest, YouTube, and/or Instagram.
  3. If you use Instagram, TikTok, or Pinterest: convert TikTok and Pinterest to Business, and Instagram to Business or Creator, first. Make Instagram public. See Business accounts. Do this before you log in.
  4. Install Google Chrome (your normal browser for those sites).
  5. You will install some Python tools one time (Python is a free helper program).
  6. Clone the project: git clone https://github.com/okwithit9-debug/the-posting-tool ~/posting-tool (or on GitHub, Code → Download ZIP).
Tip: Keep that project folder somewhere easy to find. All videos go into its inbox/ folder later.

B. Install (one time)

1. Install Python (if needed)

  1. Open python.org/downloads.
  2. Download the latest Python 3 for your computer.
  3. Run the installer.
  4. On Mac, if you see a checkbox for Install Certificates, turn it on.
  5. On Windows, turn on Add python.exe to PATH before you click Install.
a Terminal window where typing python3 --version prints a version like Python 3.12.x (Windows may use python --version).

2. Open Terminal

  1. On Mac: press Command + Space, type Terminal, press Return.
  2. On Windows: open Command Prompt or PowerShell.
  3. On Linux: open your terminal app.

3. Go into the project folder

Type this, then press Return (change the path if your folder is elsewhere):

cd ~/posting-tool

Windows example:

cd %USERPROFILE%\posting-tool
the folder name in the prompt, and no “No such file” error.

4. Install the Python dependencies

pip3 install -r requirements.txt

Windows note: if pip3 is not found, try pip install -r requirements.txt.

5. Install the browser helper

python3 -m playwright install chromium

Windows note: if needed, use python -m playwright install chromium.

the install finish with no red errors. Yellow download progress is fine.

6. Copy the sample settings file

cp config.example.json config.json

Windows:

copy config.example.json config.json

You can leave most settings alone for your first test. YouTube needs a Google allow step later (see Connect).

C. Connect your accounts

The tool uses its own Chrome profile (a separate browser home). You must be logged in there for X, Threads, TikTok, Pinterest, and Instagram. YouTube uses a separate Google allow screen.

Instagram, TikTok, and Pinterest first, if you use them. Those three need a Business account before you log in (Instagram can also be Creator). Make Instagram public first. Look for Instagram’s Schedule content switch. If it is missing on a Professional account, keep going — the tool still posts now. Full steps: Business accounts.

Log in with the login helper

  1. In Terminal, from the project folder, run:
python3 setup_playwright_logins.py
  1. A browser window opens. Log into each site you use when asked. For TikTok and Pinterest, use the Business account. For Instagram, use the Business or Creator account.
  2. Finish each login until you see your normal home/feed page.
  3. Close the helper when done.
your normal home/feed page for each site. You can re-run the helper anytime a login expires.
X note: X sometimes blocks this helper (the Next button freezes, or a “verify you are human” page appears). If that happens, solve the checkbox in regular Chrome, fully quit Chrome, then run the helper again (or run ./fix_x_cloudflare.command on Mac).

Platform notes

Platform Usual path
X Login helper. If you see a Cloudflare / “verify you are human” page, see the X note above.
Threads Login helper.
TikTok Login helper. Account must be Business first — see Business accounts.
Pinterest Login helper. Account must be Business first — see Business accounts.
Instagram Login helper. Account must be Business or Creator first — see below. If the Schedule content switch is missing on a Professional account, keep going.
YouTube Separate OAuth step (Google allow screen). Put your Google client id/secret into config.json if the README asks for them, then run: 
python3 setup_youtube_auth.py

A browser opens. Choose your Google account and click Allow.

the script finish without an error, and a token file appear under tokens/.

Instagram, TikTok, and Pinterest — Business accounts required

Read this before you log in. If you use Instagram, TikTok, or Pinterest, convert TikTok and Pinterest to Business first. Instagram can be Business or Creator. A personal account will look broken. It is not broken.

Personal account = the tool cannot do the job on that platform. Convert first. Do not open an issue until TikTok and Pinterest are Business, and Instagram is Business or Creator.

TikTok

Business is required for the link in bio on new accounts and accounts under 1k followers.

  1. Open the TikTok app or tiktok.com while logged in.
  2. Switch the account to a Business account in settings.
  3. Use that Business account when you run the login helper.

Pinterest

Business is required for scheduling.

  1. Open the Pinterest app or pinterest.com while logged in.
  2. Convert the account to a Business account in settings.
  3. Use that Business account when you run the login helper.

Instagram has extra steps (look for the Schedule content switch; keep going if a Professional account is missing it). Those are in the next section.

Instagram — Business or Creator required

Read this before you log in. Business or Creator required. Personal = stop.

Personal account = stop. Convert to Business or Creator and make the account public first. If the account is already Professional and the Schedule content switch is missing, keep going. The tool still posts now.

Convert the account first

  1. Open the Instagram app or instagram.com in Chrome.
  2. Go to Settings → Account type / Professional.
  3. Switch the account to Business (preferred) or Creator.
  4. Make the account public.

Business is preferred. Creator also works. Personal does not.

Checkpoint — do this before the first dispatch

  1. Stay logged into that Business or Creator account in the tool’s browser. The login helper needs that session.
  2. On the web, start a Reel / post as if you were going to publish.
  3. Look for a Schedule content switch in the composer.
the account is Business or Creator (not Personal). If the Schedule content switch is there, the tool can pick a time. If it is missing on a Professional account, keep going.

If the switch is there: the tool can pick a time. Same-day time scheduling is what ships.

If the account is already Professional (Business or Creator) and the switch is missing: keep going. The tool still posts. It publishes now instead of scheduling a time. That is the fallback. Instagram often hides the switch for days after you convert. This is not a broken tool. Do not open an issue only because the switch is missing.

If the account is still Personal: stop. Convert. Make it public. Personal cannot use the tool.

What Instagram can do in the tool today

  • Same-day time scheduling is what ships when the Schedule content switch is there. Other dates may publish now (fallback).
  • If the switch is missing on a Professional account, or the time cannot be set, the tool publishes now rather than using Instagram’s default time.
  • You must be logged into that Business or Creator account through the login helper.

D. First test (do this before real posts)

One small test catches most “it doesn’t work” problems early.

  1. Put one short test video into the inbox/ folder. Example name: test_clip.mp4.
  2. In the same inbox/ folder, create a matching sidecar file named test_clip.json (same name as the video, but .json).
  3. Paste this minimal example into the file (edit the caption text if you want):
{
  "title": "My first test",
  "platforms": ["x"],
  "captions": {
    "x": {
      "caption": "Test post from Posting Tool

#Test"
    }
  }
}

For multiple platforms, you can list more platforms, for example ["x", "threads", "tiktok"] or ["instagram"], and add matching caption blocks. Start with one platform for the first test. If that platform is Instagram, TikTok, or Pinterest, finish the Business checkpoint first.

  1. Run the go command from the project folder:
./posting_tool_go.command

Or:

python3 schedule_batch.py dispatch

On Mac you can also double-click posting_tool_go.command in Finder (approve it once if macOS asks).

  1. Wait until Terminal finishes.
if it worked: a receipt under posted/ (often inside a date folder). If it failed: a receipt under failed/, plus a screenshot in logs/screenshots/. Open the screenshot — it usually shows the exact problem.

E. Everyday use

  1. Drop your video and matching .json sidecar into inbox/.
  2. Names must match: my_video.mp4 + my_video.json.
  3. Run ./posting_tool_go.command (or the Python dispatch command).
  4. Do not run two dispatches at once. Wait for one to finish.
  5. Check posted/ for success or failed/ + screenshots if something breaks.

F. Troubleshooting (top problems)

If a step fails, use the AI fix prompt first: paste this guide + the error + what you see in failed/ and logs/screenshots/ (describe the screenshot; do not upload secrets). Then open a GitHub Issue if you are still stuck.

  1. Logged out / session expired. Run python3 setup_playwright_logins.py again and sign back in.
  2. X shows a Cloudflare / access / “verify you are human” page. Solve the checkbox in regular Chrome, quit Chrome, then run the login helper again or run ./fix_x_cloudflare.command.
  3. YouTube token expired. Run python3 setup_youtube_auth.py again and click Allow.
  4. Nothing in inbox / bad sidecar name. Video and JSON must sit in inbox/ and share the same base name (example: test_clip.mp4 + test_clip.json).
  5. Instagram has no Schedule content switch. Check the account type first. If it is still Personal: convert to Business or Creator, make it public, then retry. Personal cannot use the tool. If it is already Professional (Business or Creator): keep going. The tool still posts. It publishes now instead of scheduling a time. Instagram often hides the switch for days after you convert. That is not a broken tool. Do not open an issue only because the switch is missing.
  6. TikTok or Pinterest fails right after connect. Confirm the account is Business, not personal. Convert, then run the login helper and sign in again.

G. Support

Try the AI walkthrough first, then the AI fix prompt if something fails.

Still stuck? Open a GitHub Issue. General contact: support@thepostingtool.com.

Please include:

  • Which platform failed
  • A screenshot (from logs/screenshots/ if you have one)
  • The failed receipt from the failed/ folder (or paste its text)
  • If Instagram, TikTok, or Pinterest: confirm TikTok and Pinterest are Business, and Instagram is Business or Creator (not Personal). Do not open an issue only because the Instagram Schedule content switch is missing.

Want more detail after you are comfortable? Open INSTALL.md in your project folder.