Install and create your workspace

Use macOS or Linux with Python 3.11 or later, Git, and an available OS credential store or the explicit encrypted-file backend. Video validation also requires ffprobe, included with FFmpeg.

Check your Python version first. If it is older than 3.11, install a supported Python or replace python3 below with your supported interpreter, such as python3.12.

python3 --version
mkdir my-social
cd my-social
python3 -m venv .venv
source .venv/bin/activate
python -m pip install "git+https://github.com/engels-florentino/SocialCli.git"
socialcli --help
socialcli brand new MyBrand

Keep this workspace outside the application repository. In a new terminal, run cd my-social and source .venv/bin/activate before using SocialCli.

Connect your own account

Replace MyBrand with your brand name and complete MyBrand/brand.md with its voice and identity. Shared mode does not require your own developer app, client ID, client secret or pasted provider token.

socialcli connect tiktok --brand MyBrand
socialcli connections --brand MyBrand --json

Sign in directly on TikTok, grant the requested permissions, return to the terminal and confirm the displayed account. Your OS credential store must be available and unlocked. The connect command saves account identifiers in MyBrand/accounts.yml automatically. Connecting does not upload or publish content.

Hosted access today

The CLI is publicly installable. The hosted TikTok integration is currently in sandbox and accepts only authorized target accounts. Google is in Testing for authorized test users; Meta remains unpublished with development access. Installing the CLI does not make an account eligible. If your account cannot authorize yet, wait for production availability or use a service whose operator has the required provider access. Read the account connection guide before connecting.

Choose another folder

The current folder is the default. Set SOCIALCLI_ROOT to an absolute path or pass --root PATH with each command.

Headless servers

Install the explicit encrypted capability storage extra when no supported OS keyring is available. SocialCli never silently falls back.

python -m pip install "socialcli[headless-credentials] @ git+https://github.com/engels-florentino/SocialCli.git"

Follow the protected key and store setup before connecting. Use one encrypted store per brand, outside your workspace and Git repositories.

Develop and test

git clone https://github.com/engels-florentino/SocialCli.git
cd SocialCli
uv sync --group dev
uv run pytest
uv run socialcli --help

The command is socialcli. The internal Python package and earlier socialctl alias remain for compatibility. No PyPI release is announced: install from this repository.

Continue to account connections →