starflask-cli

Command-line interface for managing Starflask AI agents.

Install

npm install -g starflask-cli

Quick Start

# Sign in
starflask auth login

# List your agents
starflask agents list

# Create an agent
starflask agents create --name "my-agent"

# Fire a hook event
starflask hooks fire <agent-id> heartbeat

Authentication

# Interactive login (prompts for token)
starflask auth login

# Provide token directly
starflask auth login --token <your-token>

# Point to a different API (default: https://starflask.com)
starflask auth login --api-url https://your-instance.com

# Check who you're signed in as
starflask auth status

# Sign out
starflask auth logout

# Change API URL without re-authenticating
starflask auth set-url <url>

You can sign in with either a Clerk JWT token or a Starflask API token. The CLI will try both automatically.

Agents

# List all agents
starflask agents list

# Get agent details
starflask agents get <agent-id>

# Create an agent (interactive)
starflask agents create

# Create with flags
starflask agents create --name "my-agent" --description "Does things"

# Update an agent
starflask agents update <agent-id> --name "new-name" --description "Updated"

# Delete an agent
starflask agents delete <agent-id>
starflask agents delete <agent-id> --yes   # skip confirmation

# Activate / deactivate
starflask agents activate <agent-id>
starflask agents deactivate <agent-id>

# Link an Axoniac agent pack
starflask agents link-pack <agent-id> <axoniac-hash>

# Unlink the pack
starflask agents unlink-pack <agent-id>

# Set a heartbeat schedule (cron)
starflask agents set-heartbeat <agent-id> "*/5 * * * *"

Hooks

Hooks are the events your agent can respond to (heartbeat, discord_message, github_push, etc.).

# List available hooks for an agent
starflask hooks list <agent-id>

# Fire a hook event manually
starflask hooks fire <agent-id> heartbeat

# Fire with a JSON payload
starflask hooks fire <agent-id> discord_message --payload '{"content": "hello"}'

# Interactive event selection
starflask hooks fire <agent-id>

Sessions

Sessions are the execution history for an agent. Each time a hook fires, a session is created.

# List recent sessions
starflask sessions list <agent-id>
starflask sessions list <agent-id> --limit 50

# View full session details and result
starflask sessions get <agent-id> <session-id>

Integrations

Connect your agents to external platforms (Discord, Twitter, GitHub, Google Workspace).

# List integrations
starflask integrations list <agent-id>

# Add an integration (interactive platform picker)
starflask integrations add <agent-id>

# Add with flag
starflask integrations add <agent-id> --platform discord

# Remove an integration
starflask integrations remove <agent-id> <integration-id>

# Start an OAuth flow (prints a URL to open in your browser)
starflask integrations oauth <agent-id> discord
starflask integrations oauth <agent-id> twitter
starflask integrations oauth <agent-id> github
starflask integrations oauth <agent-id> google

# View integration keys (values are masked)
starflask integrations keys <agent-id> <integration-id>

# Set a key manually
starflask integrations set-key <agent-id> <integration-id> <key-name> <key-value>

Discord

# List guilds the bot can join
starflask integrations discord-guilds <agent-id>

# Select which guild the agent listens to
starflask integrations select-guild <agent-id> <guild-id>

GitHub

# List repos available to the agent
starflask integrations github-repos <agent-id>

# Select a repo (also sets up the webhook)
starflask integrations select-repo <agent-id> owner/repo

Tasks

Tasks are scheduled event emitters -- they fire hook events on a cron schedule.

# List tasks
starflask tasks list <agent-id>

# Create a task (interactive)
starflask tasks create <agent-id>

# Create with flags
starflask tasks create <agent-id> --name "Daily check" --event heartbeat --schedule "0 9 * * *"

# Update a task
starflask tasks update <agent-id> <task-id> --name "New name" --schedule "0 */6 * * *"

# Enable / disable
starflask tasks update <agent-id> <task-id> --enable
starflask tasks update <agent-id> <task-id> --disable

# Delete a task
starflask tasks delete <agent-id> <task-id>

Subscription & Billing

# Check subscription status and credits
starflask subscription status

# Get a link to the Stripe billing portal
starflask subscription portal

# Get a link to subscribe
starflask subscription checkout

Packs

Browse recommended agent packs and available integration platforms.

# List recommended agent packs
starflask packs list

# List available integration platforms
starflask packs apps

Command Aliases

Some commands have short aliases for convenience:

| Full Command | Alias | |---|---| | agents list | agents ls | | agents get | agents show | | agents delete | agents rm | | sessions list | sessions ls | | sessions get | sessions show | | integrations | int | | integrations list | int ls | | integrations remove | int rm | | subscription | sub | | tasks list | tasks ls | | tasks delete | tasks rm | | hooks list | hooks ls | | packs list | packs ls |

Configuration

Credentials are stored locally via conf. To see where the config file lives:

# macOS: ~/Library/Preferences/starflask-cli-nodejs/config.json
# Linux: ~/.config/starflask-cli-nodejs/config.json
# Windows: %APPDATA%/starflask-cli-nodejs/config.json

Requirements

• Node.js 18+