Setup guide

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 bought: X, Threads, TikTok, Pinterest, YouTube, and/or Instagram.
3. If you bought Instagram: convert that account to Business first. See Instagram. Do this before cookies or login.
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. After purchase, accept the private GitHub invite and clone (download) the project folder to your computer. A common place on Mac is your home folder, for example ~/posting-tool.

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.

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

4. Install the Python packages

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.

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 — two options

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.

Option 1 — Cookie bridge (recommended when it works)

This copies your login from everyday Chrome into the tool’s Chrome. Think of it as sharing a “remember me” sticker.

1. In your regular Chrome, sign into the platforms you bought (X, Threads, TikTok, Pinterest, Instagram as needed). For Instagram, that must be the Business account.
2. Confirm you can open each site without a login screen.
3. Fully quit Chrome. On Mac: Chrome menu → Quit Google Chrome (or press Command + Q). Closing the window is not enough.
4. In Terminal, go to the project folder again if needed: cd ~/posting-tool
5. Run the bridge for the sites you need (example for all browser platforms):

python3 bridge_chrome_cookies.py x.com twitter.com threads.com tiktok.com pinterest.com instagram.com

6. On Mac, if Keychain asks for permission, click Always Allow (or Allow).

Option 2 — Manual login in the tool’s browser

Use this if the bridge fails, or if you prefer to sign in by hand.

1. In Terminal, from the project folder, run:

python3 setup_playwright_logins.py

2. A browser window opens. Log into each site when asked.
3. Finish each login until you see your normal home/feed page.
4. Close the helper when done.

Which option for each platform?

python3 setup_youtube_auth.py

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

Instagram — Professional Business account required

Read this before you connect cookies or log in. Instagram only schedules on a Professional → Business account. Creator also works. Personal cannot schedule.

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.

Creator also shows the Schedule content switch. Business is preferred. Creator also works. Personal does not.

Checkpoint — do this before the first dispatch

1. Stay logged into that Business account in Chrome. The cookie bridge and Playwright login need 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.

If the switch is missing: stop. Convert the account to Business. Look again. Do not email support until you have confirmed the account is Business and you can see the switch.

What Instagram can do in this pack today

• Same-day time scheduling is what ships. Other dates may publish now (fallback).
• If the time cannot be set, the tool publishes now rather than using Instagram’s default time.
• You must be logged into that Business account in Chrome for the cookie bridge / Playwright login.

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\n\n#Test"
    }
  }
}

For a multi-platform pack, 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, finish the Business checkpoint first.

4. 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).

5. Wait until Terminal finishes.

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). Email is last resort.

1. Chrome was not fully quit before the cookie bridge. Quit Chrome with Command + Q (Mac), then bridge again.
2. Logged out / session expired. Sign in again in regular Chrome, quit Chrome, re-run the bridge — or use setup_playwright_logins.py.
3. X shows a Cloudflare / access / “verify you are human” page. Solve the checkbox in regular Chrome, quit Chrome, then bridge again or run ./fix_x_cloudflare.command.
4. YouTube token expired. Run python3 setup_youtube_auth.py again and click Allow.
5. 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).
6. Instagram has no Schedule content switch. The account is still Personal (or you are not logged into the Business account). Convert to Business, confirm the switch in the web composer, then retry. Do not email support until that checkpoint is done.

G. Support

Try the AI walkthrough first, then the AI fix prompt if something fails. Email is the last resort (30 days from purchase).

Email: support@thepostingtool.com (or the address in your purchase confirmation).

Please send:

• The tier you bought (Single / Any 3 / All 6)
• 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: confirm you converted to Business and can see the Schedule content switch

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