StatuzDocs
URL Scheme API

Accounts Action

Manage social media accounts programmatically via URL scheme

Accounts Action

Manage connected social media accounts programmatically. Add, remove, edit, and configure accounts for X, BlueSky, and Mastodon.

Syntax

statuz://accounts?action={action}&platform={platform}&[parameters]

Parameters

ParameterTypeDescriptionExample
actionstringRequired - Action to perform: add, remove, edit, set-defaultadd
platformstringRequired - Platform: x, bluesky, mastodonx
idstringAccount ID (for identification)account-123
namestringAccount username/handlejohndoe
nicknamestringAccount nicknameWork%20Account
set-nicknamestringNew nickname (for edit action)Personal
set-enabledbooleanEnable/disable accounttrue
instancestringMastodon instance URLfosstodon.org
autoConnectbooleanAuto-trigger OAuth (for add action)true

Important: Nicknames are platform-scoped. You can use the same nickname on different platforms without conflicts.

Actions

Add Account

Navigate to the account connection screen and optionally trigger OAuth automatically.

Basic Add

# Add X account
open "statuz://accounts?action=add&platform=x"

# Add BlueSky account  
open "statuz://accounts?action=add&platform=bluesky"

# Add Mastodon account (defaults to mastodon.social)
open "statuz://accounts?action=add&platform=mastodon"

Add with Custom Instance

For Mastodon, specify a custom instance:

# Add account on fosstodon
open "statuz://accounts?action=add&platform=mastodon&instance=fosstodon.org"

# Add account on mas.to
open "statuz://accounts?action=add&platform=mastodon&instance=mas.to"

Control Auto-Connection

By default, the OAuth flow triggers automatically. To only show the form:

# Show form without auto-connecting
open "statuz://accounts?action=add&platform=mastodon&autoConnect=false"

Remove Account

Disconnect and remove an account. Identify the account using one of: id, name, or nickname.

# Remove by username
open "statuz://accounts?action=remove&platform=x&name=johndoe"

# Remove by ID
open "statuz://accounts?action=remove&platform=bluesky&id=account-123"

# Remove by nickname (URL-encoded)
NICKNAME=$(printf %s "Work Account" | jq -sRr @uri)
open "statuz://accounts?action=remove&platform=x&nickname=$NICKNAME"

Edit Account

Modify account settings: nickname and enabled status.

Note: Credentials cannot be modified via URL scheme for security. OAuth must be done through the app's secure UI.

Change Nickname

# Edit by username
NICKNAME=$(printf %s "Personal Account" | jq -sRr @uri)
open "statuz://accounts?action=edit&platform=x&name=johndoe&set-nickname=$NICKNAME"

# Edit by ID
NICKNAME=$(printf %s "Work Account" | jq -sRr @uri)
open "statuz://accounts?action=edit&platform=bluesky&id=account-456&set-nickname=$NICKNAME"

Enable/Disable Account

# Disable account temporarily
open "statuz://accounts?action=edit&platform=x&name=johndoe&set-enabled=false"

# Re-enable account
open "statuz://accounts?action=edit&platform=x&name=johndoe&set-enabled=true"

Edit Multiple Fields

# Change nickname and enable
NICKNAME=$(printf %s "Main Account" | jq -sRr @uri)
open "statuz://accounts?action=edit&platform=bluesky&name=user&set-nickname=$NICKNAME&set-enabled=true"

Set Default Account

Set which account should be the default for a platform.

# Set default by username
open "statuz://accounts?action=set-default&platform=x&name=johndoe"

# Set default by nickname
NICKNAME=$(printf %s "Work Account" | jq -sRr @uri)
open "statuz://accounts?action=set-default&platform=bluesky&nickname=$NICKNAME"

# Set default by ID
open "statuz://accounts?action=set-default&platform=mastodon&id=account-789"

Platform-Specific Examples

X (Twitter) Accounts

#!/bin/bash

# Add X account
open "statuz://accounts?action=add&platform=x"

# Set nickname for identification
NICKNAME=$(printf %s "Personal Twitter" | jq -sRr @uri)
open "statuz://accounts?action=edit&platform=x&name=myhandle&set-nickname=$NICKNAME"

# Set as default
open "statuz://accounts?action=set-default&platform=x&name=myhandle"

BlueSky Accounts

#!/bin/bash

# Add BlueSky account
open "statuz://accounts?action=add&platform=bluesky"

# Edit nickname (use full handle)
NICKNAME=$(printf %s "Main Bluesky" | jq -sRr @uri)
open "statuz://accounts?action=edit&platform=bluesky&name=user.bsky.social&set-nickname=$NICKNAME"

Mastodon Accounts

#!/bin/bash

# Add account on specific instance
open "statuz://accounts?action=add&platform=mastodon&instance=mastodon.social"

# Add another instance
open "statuz://accounts?action=add&platform=mastodon&instance=fosstodon.org"

# Set default Mastodon account
open "statuz://accounts?action=set-default&platform=mastodon&name=user@mastodon.social"

Automation Workflows

Context Switching

Switch between work and personal accounts:

#!/bin/bash
# switch-work.sh

echo "Switching to work accounts..."

# Set work accounts as default
open "statuz://accounts?action=set-default&platform=x&nickname=Work%20X"
open "statuz://accounts?action=set-default&platform=bluesky&nickname=Work%20BlueSky"

# Disable personal accounts
open "statuz://accounts?action=edit&platform=x&nickname=Personal%20X&set-enabled=false"
open "statuz://accounts?action=edit&platform=bluesky&nickname=Personal%20BlueSky&set-enabled=false"

echo "Work accounts activated!"
#!/bin/bash
# switch-personal.sh

echo "Switching to personal accounts..."

# Set personal accounts as default
open "statuz://accounts?action=set-default&platform=x&nickname=Personal%20X"
open "statuz://accounts?action=set-default&platform=bluesky&nickname=Personal%20BlueSky"

# Enable personal accounts
open "statuz://accounts?action=edit&platform=x&nickname=Personal%20X&set-enabled=true"
open "statuz://accounts?action=edit&platform=bluesky&nickname=Personal%20BlueSky&set-enabled=true"

echo "Personal accounts activated!"

Bulk Account Management

#!/bin/bash
# cleanup-accounts.sh

# Disable all test accounts
TEST_ACCOUNTS=("test1" "test2" "test3")

for account in "${TEST_ACCOUNTS[@]}"; do
  echo "Disabling $account..."
  open "statuz://accounts?action=edit&platform=x&name=$account&set-enabled=false"
  sleep 0.5
done

echo "Test accounts disabled!"

Setup New Machine

#!/bin/bash
# setup-statuz-accounts.sh

echo "Setting up Statuz accounts..."

# Add all accounts
open "statuz://accounts?action=add&platform=x"
sleep 2
open "statuz://accounts?action=add&platform=bluesky"
sleep 2
open "statuz://accounts?action=add&platform=mastodon&instance=mastodon.social"
sleep 2

# Set nicknames (after OAuth completes)
read -p "Press enter after completing OAuth flows..."

# Configure nicknames
WORK_X=$(printf %s "Work Twitter" | jq -sRr @uri)
open "statuz://accounts?action=edit&platform=x&name=workhandle&set-nickname=$WORK_X"

PERSONAL_BS=$(printf %s "Personal BlueSky" | jq -sRr @uri)
open "statuz://accounts?action=edit&platform=bluesky&name=user.bsky.social&set-nickname=$PERSONAL_BS"

echo "Accounts configured!"

Account Identifiers

You can identify accounts using three methods:

1. Username/Handle

Platform-specific format:

  • X: Just the handle (no @): johndoe
  • BlueSky: Full handle with domain: user.bsky.social
  • Mastodon: User@instance format: user@mastodon.social
# X
open "statuz://accounts?action=edit&platform=x&name=johndoe&..."

# BlueSky
open "statuz://accounts?action=edit&platform=bluesky&name=user.bsky.social&..."

# Mastodon
open "statuz://accounts?action=edit&platform=mastodon&name=user@instance.social&..."

2. Nickname

Custom name you've assigned to the account. Must be URL-encoded.

NICKNAME=$(printf %s "My Work Account" | jq -sRr @uri)
open "statuz://accounts?action=edit&platform=x&nickname=$NICKNAME&..."

Platform Scoping: Nicknames are scoped per platform. You can use "Work Account" on both X and BlueSky without conflicts.

3. Account ID (UUID)

Internal account identifier. Use the MCP accounts_list tool or Settings to find IDs.

open "statuz://accounts?action=edit&platform=x&id=550e8400-e29b-41d4-a716-446655440000&..."

Error Handling

Common errors and solutions:

Account Not Found

❌ Error: "Account not found"

Solutions:

  • Verify the username/handle format is correct for the platform
  • Check capitalization matches exactly
  • For Mastodon, include the instance: user@instance.social
  • Use the MCP accounts_list tool to see exact names

Invalid Platform

❌ Error: "Invalid platform"

Fix: Use x, bluesky, or mastodon (lowercase)

Duplicate Account

❌ Error: "Account already connected"

Fix: Use the edit action instead of add

Invalid Instance URL

❌ Error: "Invalid Mastodon instance"

Solutions:

  • Verify the instance exists and is accessible
  • Use just the domain: mastodon.social (not https://)
  • Check for typos in the instance URL

Security Notes

Credentials Protection

Account passwords, tokens, and OAuth credentials are never exposed through the URL scheme:

✅ Can modify:

  • Account nickname
  • Enabled/disabled status
  • Default account selection

❌ Cannot modify:

  • OAuth tokens
  • Account passwords
  • API keys
  • Secret keys

OAuth Requirement

Adding accounts requires OAuth authentication through Statuz's secure UI:

  1. URL scheme opens the connection screen
  2. User authenticates via OAuth in-app
  3. Credentials stored securely in macOS Keychain
  4. Never exposed to URL scheme or scripts

Platform Support

PlatformIdentifierFeatures
X (Twitter)xOAuth 1.0, multiple accounts (premium)
BlueSkyblueskyOAuth 2.0, handle-based auth
MastodonmastodonOAuth 2.0, custom instances

Best Practices

  1. Use nicknames for readable account management
  2. Scope nicknames per-platform to avoid confusion
  3. Test with one account before bulk operations
  4. Handle OAuth separately - scripts can't complete OAuth
  5. Wait between operations to avoid race conditions
  6. Verify account names before bulk removal
  7. Store configurations as scripts for repeatable setups

Integration Examples

Raycast Script

#!/usr/bin/env node
// @raycast.schemaVersion 1
// @raycast.title Switch to Work Accounts
// @raycast.mode silent

const { exec } = require('child_process');

const accounts = [
  { platform: 'x', nickname: 'Work Twitter' },
  { platform: 'bluesky', nickname: 'Work BlueSky' }
];

accounts.forEach(({ platform, nickname }) => {
  const encoded = encodeURIComponent(nickname);
  exec(`open "statuz://accounts?action=set-default&platform=${platform}&nickname=${encoded}"`);
});

Alfred Workflow

Set up keywords to switch account contexts:

# Keyword: work-accounts
open "statuz://accounts?action=set-default&platform=x&nickname=Work%20X"
open "statuz://accounts?action=set-default&platform=bluesky&nickname=Work%20BS"

# Keyword: personal-accounts  
open "statuz://accounts?action=set-default&platform=x&nickname=Personal%20X"
open "statuz://accounts?action=set-default&platform=bluesky&nickname=Personal%20BS"

Related

Try Statuz today,
it's free.

Download for macOS