navig-social

Compose, schedule & publish across social networks (Studio + one-call fan-out).

Works on its own — its own CLI, no navig required · v0.2.0 · PyPI

On its own (no navig needed)

pip install navig-social
navig-social --help   # no navig needed

With navig

pip install "navig[social]"
navig social --help

NAVIG Social — compose and publish across social networks, track what each post did, and watch your own accounts over time. It runs on its own as navig-social, and inside navig as navig social / navig facebook.

On its own

pip install navig-social                          # adds the `navig-social` command
navig-social connect linkedin                     # OAuth in the browser; the token goes to the vault
navig-social fan-out --file brief.json --to x,linkedin,devto --dry-run
navig-social stats youtube @mkbhd --only-public   # public counts for any handle
navig-social facebook info                        # Facebook Page tools (`navig facebook` inside navig)

Tokens live in the shared encrypted vault (navig-vault), the same one navig reads. App credentials for connect come from the vault or the environment (LINKEDIN_CLIENT_ID, LINKEDIN_CLIENT_SECRET, …); non-secret settings such as a Facebook page id come from config.yaml or NAVIG_FACEBOOK_PAGE_ID-style variables. Receipts and engagement are recorded in the same databases navig uses, so nothing moves when you install navig later.

Part of navig, and they say so when used without it: posting to Telegram / Discord (navig's own bot), the Studio deck and its scheduler (navig's daemon), and browser-backed stats (navig's managed browser; --only-public needs no browser). presence takes a space's folder path on its own (--space ./my-space); space names need navig.

Inside navig

What it does

• Publish to X/Twitter, Facebook Page, LinkedIn, Reddit, Instagram, Threads, Pinterest, Dev.to (and Telegram) through a common BasePublisher framework.
• Fan-out — publish one brief to many networks in a single call, with per-platform adaptation + UTM tagging: navig social fan-out --file brief.json --to x,facebook,devto,telegram.
• Connect — one-command OAuth: navig social connect <network> (vault-backed tokens).
• Facebook Page admin — navig facebook (fb): check/info/set-about/photos/backup/caption/delete.
• Studio — the deck composer + scheduler (/api/deck/studio/*), fed by the background ScheduledPostService.

Commands

navig social status [--check]            # connected networks
navig social connect <network>           # OAuth connect (vault-backed)
navig social fan-out --file brief.json --to x,facebook,devto,telegram [--dry-run]
navig social stats <platform> <handle>   # PUBLIC follower/view counts for ANY handle (no account link)
navig social presence crawl --space <s>  # crawl YOUR whole roster → dated snapshot + deltas
navig social presence trend  --space <s> # first → latest movement, no re-crawl
navig facebook check | info | photos | backup | caption | delete   (alias: navig fb)

Presence — your own accounts, over time

stats answers "what is this handle's count right now". presence answers the question a portfolio owner actually asks: "what are ALL my accounts, and what moved since last time?"

It reads the roster from <space>/.navig/memory/account-registry.json, crawls each account through the same engine, and writes <space>/analytics/raw/_snapshots/presence-YYYY-MM-DD.json, diffing against the previous snapshot so no verdict is ever made on numbers of unknown age.

navig social presence crawl --space human-presence --only-public   # no browser, API/public only
navig social presence crawl --space human-presence --brand somaleto --dry-run
navig social presence trend  --space human-presence --platform telegram

• --only-public keeps it to plain HTTPS + official APIs — no CDP, no login, cron-safe.
• Successful counts are written back to the registry (--no-write-registry to skip). A failed or login-walled fetch never overwrites the last number actually observed.
• Accounts marked "snapshot_status": "dead" are skipped, so a retired handle stops being re-crawled and stops counting as a failure.
• Public metadata only. No tokens, cookies or session data are read from or written to the space.

Schedule it so the numbers are never stale:

navig cron add --name presence-weekly --schedule "0 9 * * 1" \
  --command "navig social presence crawl --space human-presence --only-public"

Install

Bundled with a full navig install (the social extra); standalone: navig store install pip:navig-social — or pip install navig-social once published. Requires navig-core in the same environment.

Credentials live in the NAVIG vault (navig vault) + config adapters.social.<network>.*. Tokens are never printed.