npx skills add https://github.com/typefully/agent-skills --skill typefully使用 Typefully 创建、安排和发布跨多个平台的社交媒体内容。
新鲜度检查:如果距离上述
last-updated日期已超过 30 天,请告知用户此技能可能已过时,并引导他们查看下方的更新选项。
源代码:github.com/typefully/agent-skills API 文档:typefully.com/docs/api
按安装类型的更新方法:
| 安装方式 | 如何更新 |
|---|---|
CLI (npx skills) | npx skills update |
| Claude Code 插件 | /plugin update typefully@typefully-skills |
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
| Cursor | 从 GitHub 自动同步远程规则 |
| 手动 | 从仓库拉取最新版本或重新复制 skills/typefully/ |
API 变更独立发布——更新技能可确保您拥有最新的命令和工作流程。
在使用此技能之前,请确保:
<skill-path>/scripts/typefully.js setup(其中 <skill-path> 是包含此 SKILL.md 的目录)export TYPEFULLY_API_KEY=your_key配置优先级(从高到低):
TYPEFULLY_API_KEY 环境变量./.typefully/config.json(项目本地,位于用户的工作目录中)~/.config/typefully/config.json(用户全局)关键:当您从 CLI 收到“未找到 API 密钥”错误时:
<skill-path>/scripts/typefully.js setup
.env 文件或其他位置搜索 API 密钥设置命令将交互式地引导用户完成配置。请信任 CLI 的错误消息并遵循其指示。
给代理的注意:本文档中的所有脚本路径(例如
./scripts/typefully.js)都是相对于此 SKILL.md 文件所在技能目录的。请根据技能安装的位置相应解析它们。
Typefully API 使用术语“社交集合”来指代用户通常所说的“帐户”。一个社交集合包含单个身份所连接的社交媒体平台(X、LinkedIn、Threads 等)。
CLI 支持一个默认社交集合 - 一旦配置,大多数命令无需指定 social_set_id 即可工作。
您可以通过以下任一方式传递社交集合:
drafts:list 123drafts:list --social-set-id 123(也支持 --social_set_id)确定使用哪个社交集合时:
config:show 查看是否已设置默认值:
./scripts/typefully.js config:show
如果配置了 default_social_set,当您省略 social_set_id 时,CLI 会自动使用它。CLAUDE.md 或 AGENTS.md:
## Typefully
Default social set ID: 12345
./scripts/typefully.js config:set-default
此命令列出可用的社交集合并将选择保存到配置文件中。| 用户说... | 操作 |
|---|---|
| “起草一条关于 X 的推文” | drafts:create --text "..."(使用默认社交集合) |
| “把这个发到 LinkedIn” | drafts:create --platform linkedin --text "..." |
| “在 LinkedIn 上提及一家公司” | linkedin:organizations:resolve --organization-url "<linkedin_url>" 然后在 drafts:create 中使用返回的 mention_text |
| “发布到 X 和 LinkedIn”(相同内容) | drafts:create --platform x,linkedin --text "..." |
| “X 线程 + LinkedIn 帖子”(不同内容) | 创建一个草稿,然后使用 drafts:update 添加平台(参见发布到多个平台) |
| “安排了什么?” | drafts:list --status scheduled |
| “显示我最近的帖子” | drafts:list --status published |
| “把这个安排到明天” | drafts:create ... --schedule "2025-01-21T09:00:00Z" |
| “立即发布这个” | drafts:create ... --schedule now 或 drafts:publish <draft_id> --use-default |
| “向草稿添加笔记/想法” | drafts:create ... --scratchpad "Your notes here" |
| “检查可用标签” | tags:list |
| “显示我上周的 X 帖子分析” | analytics:posts:list --start-date YYYY-MM-DD --end-date YYYY-MM-DD |
| “显示我包括回复在内的 X 帖子分析” | analytics:posts:list --start-date YYYY-MM-DD --end-date YYYY-MM-DD --include-replies |
| “显示我下周的队列” | queue:get --start-date YYYY-MM-DD --end-date YYYY-MM-DD |
创建帖子时请遵循此工作流程:
./scripts/typefully.js config:show
如果 default_social_set 显示一个 ID,则跳到步骤 3。./scripts/typefully.js social-sets:list
如果存在多个,询问用户使用哪个并提供将其设置为默认值:
./scripts/typefully.js config:set-default
./scripts/typefully.js drafts:create --text "Your post"
注意:如果省略 --platform,则自动选择第一个连接的平台。
对于多平台帖子:参见发布到多个平台——即使每个平台的内容不同,也始终使用单个草稿。标签有助于在 Typefully 内组织草稿。在创建新标签之前,请务必检查现有标签:
./scripts/typefully.js tags:list
./scripts/typefully.js drafts:create --text "..." --tags existing-tag-name
./scripts/typefully.js tags:create --name "New Tag"
重要:标签的作用域是每个社交集合。为一个社交集合创建的标签不会出现在另一个中。
如果需要为不同平台创建单个草稿,您需要确保创建单个草稿,而不是多个草稿。
当内容在各个平台上相同时,创建一个包含多个平台的单个草稿:
# 特定平台
./scripts/typefully.js drafts:create --platform x,linkedin --text "Big announcement!"
# 所有连接的平台
./scripts/typefully.js drafts:create --all --text "Posting everywhere!"
重要:当内容需要定制时(例如,X 线程带有 LinkedIn 帖子版本),仍然使用单个草稿——首先使用一个平台创建,然后更新以添加另一个:
# 1. 首先使用主要平台创建草稿
./scripts/typefully.js drafts:create --platform linkedin --text "Excited to share our new feature..."
# 返回:{ "id": "draft-123", ... }
# 2. 更新同一草稿以添加另一个平台及不同内容
./scripts/typefully.js drafts:update draft-123 --platform x --text "🧵 Thread time!
---
Here's what we shipped and why it matters..." --use-default
因此,请确保除非用户明确希望为每个平台使用单独的草稿,否则绝不创建多个草稿。
LinkedIn 提及通过帖子内容内的文本语法支持:
@[Company Name](urn:li:organization:123456)
使用解析器命令将公开的 LinkedIn 组织 URL 转换为可粘贴的提及语法:
# 将 LinkedIn URL 解析为提及元数据
./scripts/typefully.js linkedin:organizations:resolve --organization-url "https://www.linkedin.com/company/typefullycom/"
# 返回 mention_text,例如:@[Typefully](urn:li:organization:86779668)
然后将该 mention_text 包含在您的 LinkedIn 草稿文本中:
./scripts/typefully.js drafts:create --platform linkedin --text "Thanks @[Typefully](urn:li:organization:86779668) for the support."
| 命令 | 描述 |
|---|---|
me:get | 获取认证用户信息 |
social-sets:list | 列出您可以访问的所有社交集合 |
social-sets:get <id> | 获取社交集合详情,包括连接的平台 |
linkedin:organizations:resolve [social_set_id] --organization-url <url> | 将 LinkedIn 公司/学校 URL 解析为提及元数据(mention_text、urn) |
所有分析命令都支持可选的 [social_set_id] - 如果省略,则使用配置的默认值。
公共 API 目前在此端点上仅支持 X 帖子分析。CLI 默认将 --platform 设为 x,因此您通常可以省略它。
回复现在默认被排除,以便结果集更接近主要的已发布帖子视图。当您明确希望包含回复帖子时,请添加 --include-replies。
分析响应返回请求的包含日期范围内的帖子级别指标,包括:
impressionslikes、comments、shares、quotes、saves、profile_clicks 和 link_clicks| 命令 | 描述 |
|---|---|
analytics:posts:list [social_set_id] --start-date <YYYY-MM-DD> --end-date <YYYY-MM-DD> | 列出包含日期范围内的 X 帖子及其标准化分析指标 |
analytics:posts:list ... --start_date <YYYY-MM-DD> --end_date <YYYY-MM-DD> | 日期标志的下划线别名(从 API 文档复制) |
analytics:posts:list ... --include-replies | 在结果中包含 X 回复(默认排除) |
analytics:posts:list ... --include_replies | include-replies 标志的下划线别名 |
analytics:posts:list ... --limit 100 --offset 25 | 对结果进行分页 |
analytics:posts:list ... --platform x | 明确请求 X 分析(目前唯一支持的平台) |
所有草稿命令都支持可选的 [social_set_id] - 如果省略,则使用配置的默认值。安全注意:对于接受 [social_set_id] <draft_id> 的命令,如果您在配置了默认社交集合时仅传递单个参数(draft_id),则必须添加 --use-default 以确认意图。
| 命令 | 描述 |
|---|---|
drafts:list [social_set_id] | 列出草稿(添加 --status scheduled 进行过滤,--sort 进行排序) |
drafts:get [social_set_id] <draft_id> | 获取特定草稿及其完整内容(如果配置了默认值,单参数需要 --use-default) |
drafts:create [social_set_id] --text "..." | 创建新草稿(自动选择平台) |
drafts:create [social_set_id] --platform x --text "..." | 为特定平台创建草稿 |
drafts:create [social_set_id] --all --text "..." | 为所有连接的平台创建草稿 |
drafts:create [social_set_id] --file <path> | 从文件内容创建草稿 |
drafts:create ... --media <media_ids> | 创建带有附加媒体的草稿 |
drafts:create ... --reply-to <url> | 回复现有的 X 帖子 |
drafts:create ... --community <id> | 发布到 X 社区 |
drafts:create ... --quote-post-url <url> | 引用现有的 X 帖子 URL |
drafts:create ... --share | 为草稿生成公共分享 URL |
drafts:create ... --scratchpad "..." | 向草稿添加内部笔记/便笺 |
drafts:update [social_set_id] <draft_id> --text "..." | 更新现有草稿(如果配置了默认值,单参数需要 --use-default) |
drafts:update ... --quote-post-url <url> | 更新草稿中的 X 帖子以引用现有帖子 URL |
drafts:update [social_set_id] <draft_id> --tags "tag1,tag2" | 更新现有草稿的标签(内容不变) |
drafts:update ... --share | 为草稿生成公共分享 URL |
drafts:update ... --scratchpad "..." | 更新内部笔记/便笺 |
drafts:update [social_set_id] <draft_id> --append --text "..." | 追加到现有线程 |
安全注意:当使用默认社交集合且只有一个参数时,这些命令需要 --use-default(以防止因语法歧义导致意外操作)。
| 命令 | 描述 |
|---|---|
drafts:delete <social_set_id> <draft_id> | 删除草稿(显式 ID) |
drafts:delete <draft_id> --use-default | 使用默认社交集合删除 |
drafts:schedule <social_set_id> <draft_id> --time next-free-slot | 安排到下一个可用时段 |
drafts:schedule <draft_id> --time next-free-slot --use-default | 使用默认社交集合安排 |
drafts:publish <social_set_id> <draft_id> | 立即发布 |
drafts:publish <draft_id> --use-default | 使用默认社交集合发布 |
所有队列命令都支持可选的 [social_set_id] - 如果省略,则使用配置的默认值。
队列是一个特定于社交集合的时间线,由以下组成:
当用户询问给定帐户在某个日期范围内已安排(或空闲)的内容时,请使用 queue:get。
| 命令 | 描述 |
|---|---|
queue:get [social_set_id] --start-date <YYYY-MM-DD> --end-date <YYYY-MM-DD> | 获取一个社交集合的队列时间线:空闲队列时段加上日期范围内的已安排草稿/帖子 |
queue:get ... --start_date <YYYY-MM-DD> --end_date <YYYY-MM-DD> | 日期标志的下划线别名(从 API 文档复制) |
queue:schedule:get [social_set_id] | 获取队列计划规则 |
queue:schedule:put [social_set_id] --rules '[{"h":9,"m":30,"days":["mon","wed","fri"]}]' | 替换队列计划规则(完全替换) |
| 命令 | 描述 |
|---|---|
tags:list [social_set_id] | 列出所有标签 |
tags:create [social_set_id] --name "Tag Name" | 创建新标签 |
| 命令 | 描述 |
|---|---|
media:upload [social_set_id] <file_path> | 上传媒体,等待处理,返回就绪的 media_id |
media:upload ... --no-wait | 上传并立即返回(使用 media:status 轮询) |
media:upload ... --timeout <seconds> | 设置自定义超时(默认:60) |
media:status [social_set_id] <media_id> | 检查媒体上传状态 |
| 命令 | 描述 |
|---|---|
setup | 交互式设置 - 提示输入 API 密钥、存储位置和默认社交集合 |
| `setup --key <key> --location <global | local>` |
setup --key <key> --default-social-set <id> | 具有显式默认社交集合的非交互式设置 |
setup --key <key> --no-default | 非交互式设置,跳过默认社交集合选择 |
config:show | 显示当前配置、API 密钥来源和默认社交集合 |
config:set-default [social_set_id] | 设置默认社交集合(如果省略 ID 则为交互式) |
# 检查当前配置
./scripts/typefully.js config:show
# 设置默认值(交互式 - 列出可用社交集合)
./scripts/typefully.js config:set-default
# 设置默认值(非交互式)
./scripts/typefully.js config:set-default 123 --location global
./scripts/typefully.js drafts:create --text "Hello, world!"
./scripts/typefully.js drafts:create 123 --text "Hello, world!"
./scripts/typefully.js drafts:create --platform x,linkedin,threads --text "Big announcement!"
./scripts/typefully.js linkedin:organizations:resolve --organization-url "https://www.linkedin.com/company/typefullycom/"
./scripts/typefully.js drafts:create --platform linkedin --text "Thanks @[Typefully](urn:li:organization:86779668) for the support."
./scripts/typefully.js drafts:create --all --text "Posting everywhere!"
./scripts/typefully.js drafts:create --text "Scheduled post" --schedule next-free-slot
./scripts/typefully.js drafts:create --text "Marketing post" --tags marketing,product
./scripts/typefully.js drafts:list --status scheduled --sort scheduled_date
./scripts/typefully.js queue:get --start-date 2026-02-01 --end-date 2026-02-29
./scripts/typefully.js analytics:posts:list --start-date 2026-03-01 --end-date 2026-03-07
./scripts/typefully.js analytics:posts:list --start-date 2026-03-01 --end-date 2026-03-07 --include-replies
./scripts/typefully.js analytics:posts:list --start-date 2026-03-01 --end-date 2026-03-31 --limit 100 --offset 100
./scripts/typefully.js queue:schedule:get
./scripts/typefully.js queue:schedule:put --rules '[{"h":9,"m":30,"days":["mon","wed","fri"]}]'
./scripts/typefully.js drafts:create --platform x --text "Great thread!" --reply-to "https://x.com/user/status/123456"
./scripts/typefully.js drafts:create --platform x --text "Community update" --community 1493446837214187523
./scripts/typefully.js drafts:create --platform x --text "My take on this" --quote-post-url "https://x.com/user/status/1234567890123456789"
./scripts/typefully.js drafts:update 456 --platform x --quote-post-url "https://x.com/user/status/1234567890123456789" --use-default
./scripts/typefully.js drafts:create --text "Check this out" --share
./scripts/typefully.js drafts:create --text "Launching next week!" --scratchpad "Draft for product launch. Coordinate with marketing team before publishing."
# 单个命令处理上传 + 轮询 - 就绪时返回!
./scripts/typefully.js media:upload ./image.jpg
# 返回:{"media_id": "abc-123-def", "status": "ready", "message": "Media uploaded and ready to use"}
# 创建带有附加媒体的帖子
./scripts/typefully.js drafts:create --text "Check out this image!" --media abc-123-def
# 上传每个文件(每个都等待处理)
./scripts/typefully.js media:upload ./photo1.jpg # 返回 media_id: id1
./scripts/typefully.js media:upload ./photo2.jpg # 返回 media_id: id2
# 创建带有多个媒体的帖子(逗号分隔)
./scripts/typefully.js drafts:create --text "Photo dump!" --media id1,id2
# 上传媒体
./scripts/typefully.js media:upload ./new-image.jpg # 返回 media_id: xyz
# 使用媒体更新草稿(456 是 draft_id)
./scripts/typefully.js drafts:update 456 --text "Updated post with image" --media xyz --use-default
./scripts/typefully.js setup
# 如果只有一个社交集合存在,则自动选择默认社交集合
./scripts/typefully.js setup --key typ_xxx --location global
# 带有显式默认社交集合
./scripts/typefully.js setup --key typ_xxx --location global --default-social-set 123
# 完全跳过默认社交集合选择
./scripts/typefully.js setup --key typ_xxx --no-default
为 --platform 选项使用这些确切的名称:
x - X(前身为 Twitter)linkedin - LinkedInthreads - Threadsbluesky - Blueskymastodon - MastodonTypefully 草稿 URL 包含社交集合和草稿 ID:
https://typefully.com/?a=<social_set_id>&d=<draft_id>
示例:https://typefully.com/?a=12345&d=67890
a=12345 → social_set_idd=67890 → draft_id当用户明确要求添加笔记、想法或任何其他内容到草稿便笺时,请使用 --scratchpad 标志——不要写入本地文件!
--scratchpad 选项将内部笔记直接附加到 Typefully 草稿。这些笔记:
# 正确:笔记附加到 Typefully 中的草稿
./scripts/typefully.js drafts:create 123 --text "My post" --scratchpad "Ideas for expanding: 1) Add stats 2) Include quote"
# 错误:当用户希望笔记在 Typefully 中时,请勿将笔记写入本地文件
# 写入 /tmp/scratchpad/ 或任何本地文件不是一回事
自动化发布时,尤其是在 X 上,请遵循以下规则以保持帐户的良好状态:
如有疑问,请创建草稿供用户审核,而不是直接发布。
发布确认:除非用户明确要求“立即发布”或“立即发布”,否则在发布前务必确认。创建草稿是安全的;发布是不可逆的,并且会立即公开。
--platform,则自动选择第一个连接的平台--all 一次性发布到所有连接的平台@[Name](urn:li:organization:ID);通过 linkedin:organizations:resolve 解析 ID--- 在单独一行上拆分为多个帖子(线程)next-free-slot 让 Typefully 选择最佳时间--platform x,linkedin--title 进行内部组织(不发布到社交媒体)--scratchpad 将笔记附加到 Typefully 中的草稿(不是本地文件!)- 非常适合线程想法、研究、上下文analytics:posts:list --start-date ... --end-date ... 获取社交集合的帖子指标;回复默认被排除,--include-replies 可重新包含--file ./post.txt 代替 --text 从文件读取内容--sort 配合值如 created_at、-created_at、scheduled_date 等每周安装次数
407
仓库
GitHub 星标数
39
首次出现
2026年1月27日
安全审计
安装于
codex325
opencode323
gemini-cli310
cursor296
claude-code286
github-copilot282
Create, schedule, and publish social media content across multiple platforms using Typefully.
Freshness check : If more than 30 days have passed since the
last-updateddate above, inform the user that this skill may be outdated and point them to the update options below.
Source : github.com/typefully/agent-skills API docs : typefully.com/docs/api
Update methods by installation type:
| Installation | How to update |
|---|---|
CLI (npx skills) | npx skills update |
| Claude Code plugin | /plugin update typefully@typefully-skills |
| Cursor | Remote rules auto-sync from GitHub |
| Manual | Pull latest from repo or re-copy skills/typefully/ |
API changes ship independently—updating the skill ensures you have the latest commands and workflows.
Before using this skill, ensure:
API Key : Run the setup command to configure your API key securely
<skill-path>/scripts/typefully.js setup (where <skill-path> is the directory containing this SKILL.md)export TYPEFULLY_API_KEY=your_keyRequirements : Node.js 18+ (for built-in fetch API). No other dependencies needed.
Config priority (highest to lowest):
TYPEFULLY_API_KEY environment variable./.typefully/config.json (project-local, in user's working directory)~/.config/typefully/config.json (user-global)CRITICAL : When you receive an "API key not found" error from the CLI:
Tell the user to run the setup command - The setup is interactive and requires user input, so you cannot run it on their behalf. Recommend they run it themselves, using the correct path based on where this skill was loaded:
<skill-path>/scripts/typefully.js setup
Stop and wait - After telling the user to run setup, do not continue with the task. You cannot create drafts, upload media, or perform any API operations without a valid API key. Wait for the user to complete setup and confirm before proceeding.
DO NOT attempt any of the following:
.env files, or other locationsThe setup command will interactively guide the user through configuration. Trust the CLI's error messages and follow their instructions.
Note for agents : All script paths in this document (e.g.,
./scripts/typefully.js) are relative to the skill directory where this SKILL.md file is located. Resolve them accordingly based on where the skill is installed.
The Typefully API uses the term "social set" to refer to what users commonly call an "account". A social set contains the connected social media platforms (X, LinkedIn, Threads, etc.) for a single identity.
The CLI supports a default social set - once configured, most commands work without specifying the social_set_id.
You can pass the social set either way :
drafts:list 123drafts:list --social-set-id 123 (also supports --social_set_id)When determining which social set to use:
Check for a configured default first - Run config:show to see if a default is already set:
./scripts/typefully.js config:show
If default_social_set is configured, the CLI uses it automatically when you omit the social_set_id.
Check project context - Look for configuration in project files like CLAUDE.md or AGENTS.md:
## Typefully
Default social set ID: 12345
Single social set shortcut - If the user only has one social set and no default is configured, use it automatically
Multiple social sets, no default - Ask the user which to use, then offer to save their choice as the default :
./scripts/typefully.js config:set-default
This command lists available social sets and saves the choice to the config file.
| User says... | Action |
|---|---|
| "Draft a tweet about X" | drafts:create --text "..." (uses default social set) |
| "Post this to LinkedIn" | drafts:create --platform linkedin --text "..." |
| "Mention a company on LinkedIn" | linkedin:organizations:resolve --organization-url "<linkedin_url>" then use returned mention_text in drafts:create |
| "Post to X and LinkedIn" (same content) | drafts:create --platform x,linkedin --text "..." |
Follow this workflow when creating posts:
Check if a default social set is configured :
./scripts/typefully.js config:show
If default_social_set shows an ID, skip to step 3.
If no default, list social sets to find available options:
./scripts/typefully.js social-sets:list
If multiple exist, ask the user which to use and offer to set it as default:
./scripts/typefully.js config:set-default
3. Create drafts (social_set_id is optional if default is configured):
./scripts/typefully.js drafts:create --text "Your post"
Note: If --platform is omitted, the first connected platform is auto-selected.
For multi-platform posts : See Publishing to Multiple Platforms — always use a single draft, even when content differs per platform.
Tags help organize drafts within Typefully. Always check existing tags before creating new ones :
List existing tags first :
./scripts/typefully.js tags:list
Use existing tags when available - if a tag with the desired name already exists, use it directly when creating drafts:
./scripts/typefully.js drafts:create --text "..." --tags existing-tag-name
Only create new tags if needed - if the tag doesn't exist, create it:
./scripts/typefully.js tags:create --name "New Tag"
Important : Tags are scoped to each social set. A tag created for one social set won't appear in another.
If a single draft needs to be created for different platforms, you need to make sure to create a single draft and not multiple drafts.
When the content is the same across platforms, create a single draft with multiple platforms:
# Specific platforms
./scripts/typefully.js drafts:create --platform x,linkedin --text "Big announcement!"
# All connected platforms
./scripts/typefully.js drafts:create --all --text "Posting everywhere!"
IMPORTANT : When content should be tailored (e.g., X thread with a LinkedIn post version), still use a single draft — create with one platform first, then update to add the other:
# 1. Create draft with the primary platform first
./scripts/typefully.js drafts:create --platform linkedin --text "Excited to share our new feature..."
# Returns: { "id": "draft-123", ... }
# 2. Update the same draft to add another platform with different content
./scripts/typefully.js drafts:update draft-123 --platform x --text "🧵 Thread time!
---
Here's what we shipped and why it matters..." --use-default
So make sure to NEVER create multiple drafts unless the user explicitly wants separate drafts for each platform.
LinkedIn mentions are supported via text syntax inside post content:
@[Company Name](urn:li:organization:123456)
Use the resolver command to convert a public LinkedIn organization URL into ready-to-paste mention syntax:
# Resolve a LinkedIn URL into mention metadata
./scripts/typefully.js linkedin:organizations:resolve --organization-url "https://www.linkedin.com/company/typefullycom/"
# Returns mention_text like: @[Typefully](urn:li:organization:86779668)
Then include that mention_text in your LinkedIn draft text:
./scripts/typefully.js drafts:create --platform linkedin --text "Thanks @[Typefully](urn:li:organization:86779668) for the support."
| Command | Description |
|---|---|
me:get | Get authenticated user info |
social-sets:list | List all social sets you can access |
social-sets:get <id> | Get social set details including connected platforms |
linkedin:organizations:resolve [social_set_id] --organization-url <url> | Resolve LinkedIn company/school URL into mention metadata (mention_text, urn) |
All analytics commands support an optional [social_set_id] - if omitted, the configured default is used.
The public API currently supports X post analytics only on this endpoint. The CLI defaults --platform to x, so you can usually omit it.
Replies are now excluded by default so the result set matches the main published-post view more closely. Add --include-replies when you explicitly want reply posts included.
Analytics responses return post-level metrics for the requested inclusive date range, including:
impressionslikes, comments, shares, quotes, saves, profile_clicks, and link_clicks| Command | Description |
|---|---|
analytics:posts:list [social_set_id] --start-date <YYYY-MM-DD> --end-date <YYYY-MM-DD> | List X posts with normalized analytics metrics for an inclusive date range |
analytics:posts:list ... --start_date <YYYY-MM-DD> --end_date <YYYY-MM-DD> | Snake case aliases for date flags (copied from API docs) |
analytics:posts:list ... --include-replies | Include X replies in the results (excluded by default) |
analytics:posts:list ... --include_replies | Snake case alias for the include-replies flag |
analytics:posts:list ... --limit 100 --offset 25 |
All drafts commands support an optional [social_set_id] - if omitted, the configured default is used. Safety note : For commands that take [social_set_id] <draft_id>, if you pass only a single argument (the draft_id) while a default social set is configured, you must add --use-default to confirm intent.
| Command | Description |
|---|---|
drafts:list [social_set_id] | List drafts (add --status scheduled to filter, --sort to order) |
drafts:get [social_set_id] <draft_id> | Get a specific draft with full content (single-arg requires --use-default if a default is configured) |
drafts:create [social_set_id] --text "..." | Create a new draft (auto-selects platform) |
drafts:create [social_set_id] --platform x --text "..." |
Safety note : These commands require --use-default when using the default social set with a single argument (to prevent accidental operations from ambiguous syntax).
| Command | Description |
|---|---|
drafts:delete <social_set_id> <draft_id> | Delete a draft (explicit IDs) |
drafts:delete <draft_id> --use-default | Delete using default social set |
drafts:schedule <social_set_id> <draft_id> --time next-free-slot | Schedule to next available slot |
drafts:schedule <draft_id> --time next-free-slot --use-default | Schedule using default social set |
drafts:publish <social_set_id> <draft_id> | Publish immediately |
All queue commands support an optional [social_set_id] - if omitted, the configured default is used.
The queue is a social-set-specific timeline made of:
Use queue:get when the user asks what is already scheduled (or free) for a given account in a date range.
| Command | Description |
|---|---|
queue:get [social_set_id] --start-date <YYYY-MM-DD> --end-date <YYYY-MM-DD> | Get the queue timeline for one social set: free queue slots plus scheduled drafts/posts in a date range |
queue:get ... --start_date <YYYY-MM-DD> --end_date <YYYY-MM-DD> | Snake case aliases for date flags (copied from API docs) |
queue:schedule:get [social_set_id] | Get queue schedule rules |
queue:schedule:put [social_set_id] --rules '[{"h":9,"m":30,"days":["mon","wed","fri"]}]' | Replace queue schedule rules (full replacement) |
| Command | Description |
|---|---|
tags:list [social_set_id] | List all tags |
tags:create [social_set_id] --name "Tag Name" | Create a new tag |
| Command | Description |
|---|---|
media:upload [social_set_id] <file_path> | Upload media, wait for processing, return ready media_id |
media:upload ... --no-wait | Upload and return immediately (use media:status to poll) |
media:upload ... --timeout <seconds> | Set custom timeout (default: 60) |
media:status [social_set_id] <media_id> | Check media upload status |
| Command | Description |
|---|---|
setup | Interactive setup - prompts for API key, storage location, and default social set |
| `setup --key <key> --location <global | local>` |
setup --key <key> --default-social-set <id> | Non-interactive setup with explicit default social set |
setup --key <key> --no-default | Non-interactive setup, skip default social set selection |
config:show | Show current config, API key source, and default social set |
config:set-default [social_set_id] | Set default social set (interactive if ID omitted) |
# Check current config
./scripts/typefully.js config:show
# Set default (interactive - lists available social sets)
./scripts/typefully.js config:set-default
# Set default (non-interactive)
./scripts/typefully.js config:set-default 123 --location global
./scripts/typefully.js drafts:create --text "Hello, world!"
./scripts/typefully.js drafts:create 123 --text "Hello, world!"
./scripts/typefully.js drafts:create --platform x,linkedin,threads --text "Big announcement!"
./scripts/typefully.js linkedin:organizations:resolve --organization-url "https://www.linkedin.com/company/typefullycom/"
./scripts/typefully.js drafts:create --platform linkedin --text "Thanks @[Typefully](urn:li:organization:86779668) for the support."
./scripts/typefully.js drafts:create --all --text "Posting everywhere!"
./scripts/typefully.js drafts:create --text "Scheduled post" --schedule next-free-slot
./scripts/typefully.js drafts:create --text "Marketing post" --tags marketing,product
./scripts/typefully.js drafts:list --status scheduled --sort scheduled_date
./scripts/typefully.js queue:get --start-date 2026-02-01 --end-date 2026-02-29
./scripts/typefully.js analytics:posts:list --start-date 2026-03-01 --end-date 2026-03-07
./scripts/typefully.js analytics:posts:list --start-date 2026-03-01 --end-date 2026-03-07 --include-replies
./scripts/typefully.js analytics:posts:list --start-date 2026-03-01 --end-date 2026-03-31 --limit 100 --offset 100
./scripts/typefully.js queue:schedule:get
./scripts/typefully.js queue:schedule:put --rules '[{"h":9,"m":30,"days":["mon","wed","fri"]}]'
./scripts/typefully.js drafts:create --platform x --text "Great thread!" --reply-to "https://x.com/user/status/123456"
./scripts/typefully.js drafts:create --platform x --text "Community update" --community 1493446837214187523
./scripts/typefully.js drafts:create --platform x --text "My take on this" --quote-post-url "https://x.com/user/status/1234567890123456789"
./scripts/typefully.js drafts:update 456 --platform x --quote-post-url "https://x.com/user/status/1234567890123456789" --use-default
./scripts/typefully.js drafts:create --text "Check this out" --share
./scripts/typefully.js drafts:create --text "Launching next week!" --scratchpad "Draft for product launch. Coordinate with marketing team before publishing."
# Single command handles upload + polling - returns when ready!
./scripts/typefully.js media:upload ./image.jpg
# Returns: {"media_id": "abc-123-def", "status": "ready", "message": "Media uploaded and ready to use"}
# Create post with the media attached
./scripts/typefully.js drafts:create --text "Check out this image!" --media abc-123-def
# Upload each file (each waits for processing)
./scripts/typefully.js media:upload ./photo1.jpg # Returns media_id: id1
./scripts/typefully.js media:upload ./photo2.jpg # Returns media_id: id2
# Create post with multiple media (comma-separated)
./scripts/typefully.js drafts:create --text "Photo dump!" --media id1,id2
# Upload media
./scripts/typefully.js media:upload ./new-image.jpg # Returns media_id: xyz
# Update draft with media (456 is the draft_id)
./scripts/typefully.js drafts:update 456 --text "Updated post with image" --media xyz --use-default
./scripts/typefully.js setup
# Auto-selects default social set if only one exists
./scripts/typefully.js setup --key typ_xxx --location global
# With explicit default social set
./scripts/typefully.js setup --key typ_xxx --location global --default-social-set 123
# Skip default social set selection entirely
./scripts/typefully.js setup --key typ_xxx --no-default
Use these exact names for the --platform option:
x - X (formerly Twitter)linkedin - LinkedInthreads - Threadsbluesky - Blueskymastodon - MastodonTypefully draft URLs contain the social set and draft IDs:
https://typefully.com/?a=<social_set_id>&d=<draft_id>
Example: https://typefully.com/?a=12345&d=67890
a=12345 → social_set_idd=67890 → draft_idWhen the user explictly asked to add notes, ideas, or anything else in the draft scratchpad, use the--scratchpad flag—do NOT write to local files!
The --scratchpad option attaches internal notes directly to the Typefully draft. These notes:
Are visible in the Typefully UI alongside the draft
Stay attached to the draft permanently
Are private and never published to social media
Are perfect for storing thread expansion ideas, research notes, context, etc.
./scripts/typefully.js drafts:create 123 --text "My post" --scratchpad "Ideas for expanding: 1) Add stats 2) Include quote"
When automating posts, especially on X, follow these rules to keep accounts in good standing:
When in doubt, create drafts for user review rather than publishing directly.
Publishing confirmation : Unless the user explicitly asks to "publish now" or "post immediately", always confirm before publishing. Creating a draft is safe; publishing is irreversible and goes public instantly.
--platform is omitted, the first connected platform is auto-selected--all to post to all connected platforms at once@[Name](urn:li:organization:ID) in post text; resolve IDs via linkedin:organizations:resolve--- on its own line to split into multiple posts (thread)next-free-slot to let Typefully pick the optimal time--platform x,linkedinWeekly Installs
407
Repository
GitHub Stars
39
First Seen
Jan 27, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
codex325
opencode323
gemini-cli310
cursor296
claude-code286
github-copilot282
营销心理学与心智模型应用指南 | 提升营销决策与客户行为理解
37,100 周安装
| "X thread + LinkedIn post" (different content) | Create one draft, then drafts:update to add platform (see Publishing to Multiple Platforms) |
| "What's scheduled?" | drafts:list --status scheduled |
| "Show my recent posts" | drafts:list --status published |
| "Schedule this for tomorrow" | drafts:create ... --schedule "2025-01-21T09:00:00Z" |
| "Post this now" | drafts:create ... --schedule now or drafts:publish <draft_id> --use-default |
| "Add notes/ideas to the draft" | drafts:create ... --scratchpad "Your notes here" |
| "Check available tags" | tags:list |
| "Show my X post analytics for last week" | analytics:posts:list --start-date YYYY-MM-DD --end-date YYYY-MM-DD |
| "Show my X post analytics including replies" | analytics:posts:list --start-date YYYY-MM-DD --end-date YYYY-MM-DD --include-replies |
| "Show my queue for next week" | queue:get --start-date YYYY-MM-DD --end-date YYYY-MM-DD |
| Paginate through results |
analytics:posts:list ... --platform x | Explicitly request X analytics (currently the only supported platform) |
| Create a draft for specific platform(s) |
drafts:create [social_set_id] --all --text "..." | Create a draft for all connected platforms |
drafts:create [social_set_id] --file <path> | Create draft from file content |
drafts:create ... --media <media_ids> | Create draft with attached media |
drafts:create ... --reply-to <url> | Reply to an existing X post |
drafts:create ... --community <id> | Post to an X community |
drafts:create ... --quote-post-url <url> | Quote an existing X post URL |
drafts:create ... --share | Generate a public share URL for the draft |
drafts:create ... --scratchpad "..." | Add internal notes/scratchpad to the draft |
drafts:update [social_set_id] <draft_id> --text "..." | Update an existing draft (single-arg requires --use-default if a default is configured) |
drafts:update ... --quote-post-url <url> | Update X post(s) in a draft to quote an existing post URL |
drafts:update [social_set_id] <draft_id> --tags "tag1,tag2" | Update tags on an existing draft (content unchanged) |
drafts:update ... --share | Generate a public share URL for the draft |
drafts:update ... --scratchpad "..." | Update internal notes/scratchpad |
drafts:update [social_set_id] <draft_id> --append --text "..." | Append to existing thread |
drafts:publish <draft_id> --use-default| Publish using default social set |
--title for internal organization (not posted to social media)--scratchpad to attach notes to the draft in Typefully (NOT local files!) - perfect for thread ideas, research, contextanalytics:posts:list --start-date ... --end-date ... to fetch post metrics for a social set; replies are excluded by default, and --include-replies opts back in--file ./post.txt instead of --text to read content from a file--sort with values like created_at, -created_at, scheduled_date, etc.