# Typefully

> >

- **Type:** Skill
- **Install:** `agentstack add skill-ahmadawais-typefully-cli-skills`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ahmadawais](https://agentstack.voostack.com/s/ahmadawais)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ahmadawais](https://github.com/ahmadawais)
- **Source:** https://github.com/ahmadawais/typefully-cli/tree/main/skills
- **Website:** https://x.com/MrAhmadAwais

## Install

```sh
agentstack add skill-ahmadawais-typefully-cli-skills
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Typefully Skill

Create, schedule, and publish social media content across multiple platforms using [Typefully](https://typefully.com).

## Quick Start

```bash
tfly                              # interactive — pick text, platform, schedule
tfly "Hello, world!"              # instant draft (uses default platforms)
tfly rm                           # interactive draft picker to delete
tfly rm                 # delete specific draft
```

### Handling "API key not found" errors

**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:
```sh
typefully setup
```

## Social Sets

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**:
- Positional: `typefully drafts list 123`
- Flag: `typefully drafts list --social-set-id 123`

When determining which social set to use:

1. **Check for a configured default first** - Run `typefully config show` to see if a default is already set:
   ```sh
   typefully config show
   ```
   If `default_social_set` is configured, the CLI uses it automatically when you omit the social_set_id.

2. **Check project context** - Look for configuration in project files like `CLAUDE.md` or `AGENTS.md`:

   ```markdown
   ## Typefully
   Default social set ID: 12345
   ```

3. **Single social set shortcut** - If the user only has one social set and no default is configured, use it automatically

4. **Multiple social sets, no default** - Ask the user which to use, then **offer to save their choice as the default**:
   ```sh
   typefully config set-default
   ```
   This command lists available social sets and saves the choice to the config file.

5. **Reuse previously resolved social set** - If determined earlier in the session, use it without asking again

## Common Actions

| User says... | Action |
|--------------|--------|
| "Draft a tweet about X" | `typefully drafts create --text "..."` (uses default social set) |
| "Post this to LinkedIn" | `typefully drafts create --platform linkedin --text "..."` |
| "Post to X and LinkedIn" (same content) | `typefully drafts create --platform x,linkedin --text "..."` |
| "X thread + LinkedIn post" (different content) | Create one draft, then `typefully drafts update` to add platform (see [Publishing to Multiple Platforms](#publishing-to-multiple-platforms)) |
| "What's scheduled?" | `typefully drafts list --status scheduled` |
| "Show my recent posts" | `typefully drafts list --status published` |
| "Schedule this for tomorrow" | `typefully drafts create ... --schedule "2025-01-21T09:00:00Z"` |
| "Post this now" | `typefully drafts create ... --schedule now` or `typefully drafts publish  --use-default` |
| "Add notes/ideas to the draft" | `typefully drafts create ... --scratchpad "Your notes here"` |
| "Set my default platforms" | `typefully config set-platforms` |
| "Delete a draft" | `tfly rm [draft_id]` |
| "Check available tags" | `typefully tags list` |

## Workflow

Follow this workflow when creating posts:

1. **Check if a default social set is configured**:
   ```sh
   typefully config show
   ```
   If `default_social_set` shows an ID, skip to step 3.

2. **If no default, list social sets** to find available options:
   ```sh
   typefully social-sets list
   ```
   If multiple exist, ask the user which to use and offer to set it as default:
   ```sh
   typefully config set-default
   ```

3. **Create drafts** (social_set_id is optional if default is configured):
   ```sh
   typefully drafts create --text "Your post"
   ```
   Note: If `--platform` is omitted, uses `defaultPlatforms` config if set, else first connected platform. Set defaults with `typefully config set-platforms`.

   **For multi-platform posts**: See [Publishing to Multiple Platforms](#publishing-to-multiple-platforms) — always use a single draft, even when content differs per platform.

4. **Schedule or publish** as needed

## Working with Tags

Tags help organize drafts within Typefully. **Always check existing tags before creating new ones**:

1. **List existing tags first**:
   ```sh
   typefully tags list
   ```

2. **Use existing tags when available** - if a tag with the desired name already exists, use it directly when creating drafts:
   ```sh
   typefully drafts create --text "..." --tags existing-tag-name
   ```

3. **Only create new tags if needed** - if the tag doesn't exist, create it:
   ```sh
   typefully 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.

## Publishing to Multiple Platforms

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:

```sh
# Specific platforms
typefully drafts create --platform x,linkedin,threads,bluesky --text "Big announcement!"

# All connected platforms
typefully 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:

```sh
# 1. Create draft with the primary platform first
typefully 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
typefully 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.

## Commands Reference

### User & Social Sets

| Command | Description |
|---------|-------------|
| `typefully me` | Get authenticated user info |
| `typefully social-sets list` | List all social sets you can access |
| `typefully social-sets get ` | Get social set details including connected platforms |

### Drafts

All drafts commands support an optional `[social_set_id]` positional argument or `--social-set-id ` flag — if omitted, the configured default is used.
**Safety note**: For commands that take `[social_set_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 |
|---------|-------------|
| `typefully drafts list [social_set_id]` | List drafts (add `--status scheduled` to filter, `--sort` to order) |
| `typefully drafts get [social_set_id] ` | Get a specific draft with full content (single-arg requires `--use-default` if a default is configured) |
| `typefully drafts create [social_set_id] --text "..."` | Create a new draft (auto-selects platform) |
| `typefully drafts create [social_set_id] --platform x --text "..."` | Create a draft for specific platform(s) |
| `typefully drafts create [social_set_id] --all --text "..."` | Create a draft for all connected platforms |
| `typefully drafts create [social_set_id] --file ` | Create draft from file content |
| `typefully drafts create ... --media ` | Create draft with attached media |
| `typefully drafts create ... --reply-to ` | Reply to an existing X post |
| `typefully drafts create ... --community ` | Post to an X community |
| `typefully drafts create ... --share` | Generate a public share URL for the draft |
| `typefully drafts create ... --scratchpad "..."` | Add internal notes/scratchpad to the draft |
| `typefully drafts update [social_set_id]  --text "..."` | Update an existing draft (single-arg requires `--use-default` if a default is configured) |
| `typefully drafts update [social_set_id]  --tags "tag1,tag2"` | Update tags on an existing draft (content unchanged) |
| `typefully drafts update ... --share` | Generate a public share URL for the draft |
| `typefully drafts update ... --scratchpad "..."` | Update internal notes/scratchpad |
| `typefully drafts update [social_set_id]  --append --text "..."` | Append to existing thread |

### Scheduling & Publishing

**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 |
|---------|-------------|
| `typefully drafts delete  ` | Delete a draft (explicit IDs) |
| `typefully drafts delete  --use-default` | Delete using default social set |
| `typefully drafts schedule   --time next-free-slot` | Schedule to next available slot |
| `typefully drafts schedule  --time next-free-slot --use-default` | Schedule using default social set |
| `typefully drafts publish  ` | Publish immediately |
| `typefully drafts publish  --use-default` | Publish using default social set |

### Tags

| Command | Description |
|---------|-------------|
| `typefully tags list [social_set_id]` | List all tags |
| `typefully tags create [social_set_id] --name "Tag Name"` | Create a new tag |

### Media

| Command | Description |
|---------|-------------|
| `typefully media upload  [social_set_id]` | Upload media, wait for processing, return ready media_id |
| `typefully media upload  --no-wait` | Upload and return immediately (use media status to poll) |
| `typefully media upload  --timeout ` | Set custom timeout (default: 60) |
| `typefully media status  [social_set_id]` | Check media upload status |

### Setup & Configuration

| Command | Description |
|---------|-------------|
| `typefully setup` | Interactive setup - prompts for API key, storage location, and default social set |
| `typefully setup --key  --location ` | Non-interactive setup for scripts/CI (auto-selects default if only one social set) |
| `typefully setup --key  --default-social-set ` | Non-interactive setup with explicit default social set |
| `typefully setup --key  --no-default` | Non-interactive setup, skip default social set selection |
| `typefully config show` | Show current config, API key source, and default social set |
| `typefully config set-default [social_set_id]` | Set default social set (interactive if ID omitted) |
| `typefully config set-platforms` | Set default platforms used when creating drafts (interactive multiselect) |
| `typefully config set-platforms --platforms x,linkedin` | Set default platforms non-interactively |

### Shortcuts (`tfly`)

`tfly` is a short alias for `typefully`. The default command creates drafts directly:

| Command | Description |
|---------|-------------|
| `tfly "text"` | Create draft instantly with default platforms — no flags needed |
| `tfly` | Interactive flow: prompts for text, platforms (pre-ticked from config), and schedule |
| `tfly rm` | Interactive picker — loads drafts, pick one or more to delete |
| `tfly rm ` | Delete a specific draft directly |
| `tfly create-draft "text"` | Full `create-draft` alias with all flag support |
| `tfly update-draft  "text"` | Full `update-draft` alias with all flag support |

## Examples

### Set up default social set
```sh
# Check current config
typefully config show

# Set default (interactive - lists available social sets)
typefully config set-default

# Set default (non-interactive)
typefully config set-default 123 --location global
```

### Create a tweet (using default social set)
```sh
typefully drafts create --text "Hello, world!"
```

### Create a tweet with explicit social_set_id
```sh
# Positional
typefully drafts create 123 --text "Hello, world!"

# Flag
typefully drafts create --social-set-id 123 --text "Hello, world!"
```

### Create a cross-platform post (specific platforms)
```sh
typefully drafts create --platform x,linkedin,threads --text "Big announcement!"
```

### Create a post on all connected platforms
```sh
typefully drafts create --all --text "Posting everywhere!"
```

### Create and schedule for next slot
```sh
typefully drafts create --text "Scheduled post" --schedule next-free-slot
```

### Create with tags
```sh
typefully drafts create --text "Marketing post" --tags marketing,product
```

### List scheduled posts sorted by date
```sh
typefully drafts list --status scheduled --sort scheduled_date
```

### Reply to a tweet
```sh
typefully drafts create --platform x --text "Great thread!" --reply-to "https://x.com/user/status/123456"
```

### Post to an X community
```sh
typefully drafts create --platform x --text "Community update" --community 1493446837214187523
```

### Create draft with share URL
```sh
typefully drafts create --text "Check this out" --share
```

### Create draft with scratchpad notes
```sh
typefully drafts create --text "Launching next week!" --scratchpad "Draft for product launch. Coordinate with marketing team before publishing."
```

### Upload media and create post with it
```sh
# Single command handles upload + polling - returns when ready!
typefully media upload ./image.jpg
# Returns: {"media_id": "abc-123-def", "status": "ready", "message": "Media uploaded and ready"}

# Create post with the media attached
typefully drafts create --text "Check out this image!" --media abc-123-def
```

### Upload multiple media files
```sh
# Upload each file (each waits for processing)
typefully media upload ./photo1.jpg  # Returns media_id: id1
typefully media upload ./photo2.jpg  # Returns media_id: id2

# Create post with multiple media (comma-separated)
typefully drafts create --text "Photo dump!" --media id1,id2
```

### Add media to an existing draft
```sh
# Upload media
typefully media upload ./new-image.jpg  # Returns media_id: xyz

# Update draft with media (456 is the draft_id)
typefully drafts update 456 --text "Updated post with image" --media xyz --use-default
```

### Setup (interactive)
```sh
typefully setup
```

### Setup (non-interactive, for scripts/CI)
```sh
# Auto-selects default social set if only one exists
typefully setup --key typ_xxx --location global

# With explicit default social set
typefully setup --key typ_xxx --location global --default-social-set 123

# Skip default social set selection entirely
typefully setup --key typ_xxx --no-default
```

## Platform Names

Use these exact names for the `--platform` option:
- `x` - X (formerly Twitter)
- `linkedin` - LinkedIn
- `threads` - Threads
- `bluesky` - Bluesky
- `mastodon` - Mastodon

## Draft URLs

Typefully draft URLs contain the social set and draft IDs:
```
https://typefully.com/?a=&d=
```

Example: `https://typefully.com/?a=12345&d=67890`
- `a=12345` → social_set_id
- `d=67890` → draft_id

## Draft Scratchpad

**When the user explicitly asks 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.

```sh
# CORRECT: Notes attached to the draft in Typefully
typefully drafts create --social-set-id 123 --text "My post" --scratchpad "Ideas for expanding: 1) Add stats 2) Include quote"

# WRONG: Do NOT write notes to local files when the user wants them in Typefully
# Writing to /tmp/scratchpad/ or any local file is NOT the same thing
```

## Automation Guidelines

When automating posts, especially on X, follow these rules to keep accounts in good standing:

- **No duplicate content** across multiple accounts
- **No unsolicited automated replies** - only reply when explicitly requested by the user

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ahmadawais](https://github.com/ahmadawais)
- **Source:** [ahmadawais/typefully-cli](https://github.com/ahmadawais/typefully-cli)
- **License:** MIT
- **Homepage:** https://x.com/MrAhmadAwais

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ahmadawais-typefully-cli-skills
- Seller: https://agentstack.voostack.com/s/ahmadawais
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.