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, available integration platforms, and provision custom packs.

# List recommended agent packs
starflask packs list

# List available integration platforms
starflask packs apps

# Provision a custom pack from a JSON file and link it to an agent
starflask agents provision-pack <agent-id> --file pack.json

Provisioning a custom agent pack

The provision-pack command reads a JSON file that defines the agent's soul, personas, and hook mappings, then uploads it to Starflask and links it to the agent in one step. Provisioning is idempotent — the same content always produces the same content_hash, and updated content replaces the agent's existing pack.

Pack definition schema

{
  "soul": {
    "name": "my_agent",
    "description": "A short description of the agent's purpose",
    "content": "You are a helpful assistant that specializes in ...",
    "tags": ["assistant", "support"]
  },
  "personas": [
    {
      "name": "default",
      "description": "Default response persona",
      "content": "Respond concisely and helpfully. Use a friendly tone."
    },
    {
      "name": "analyst",
      "description": "Data analysis mode",
      "content": "Analyze the data carefully and return structured JSON results."
    }
  ],
  "pack": {
    "name": "my_pack",
    "description": "My custom agent behavior pack",
    "hooks": {
      "greet": {
        "persona": "default",
        "template": "Say hello to {{name}} and introduce yourself."
      },
      "analyze_data": {
        "persona": "analyst",
        "template": "Analyze the following data: {{data}}"
      }
    }
  }
}

Schema fields

| Field | Type | Description | |---|---|---| | soul.name | string | Internal identifier for the agent's core identity | | soul.description | string | Short description of the agent's purpose | | soul.content | string | The system prompt that defines who the agent is and how it behaves | | soul.tags | string[] | Tags for categorization | | personas[].name | string | Unique name for this persona (referenced by hooks) | | personas[].description | string | Short description of this behavioral mode | | personas[].content | string | Prompt that gets appended to the soul when this persona is active | | pack.name | string | Name of the pack | | pack.description | string | Short description of the pack | | pack.hooks | object | Map of event names to hook definitions | | pack.hooks.<event>.persona | string | Which persona to use when this hook fires | | pack.hooks.<event>.template | string | Prompt template with {{variable}} placeholders filled from the hook payload |

How it works

1. Soul is the agent's base system prompt — always present in every interaction
2. Personas are behavioral modes. When a hook fires, the soul prompt + the selected persona's prompt are combined as the system context
3. Hooks map event names to persona + template pairs. When your app calls fire_hook with an event name and payload, the template's {{variables}} are replaced with payload values

Example: building and provisioning with an AI coding agent

An AI coding agent like Claude Code can create a Starflask agent and provision a custom pack in a single workflow:

# 1. Create the agent
starflask agents create --name "support-bot"
# Agent created: support-bot (ag_abc123)

# 2. Write the pack definition
cat > pack.json << 'EOF'
{
  "soul": {
    "name": "support_bot",
    "description": "Customer support agent",
    "content": "You are a friendly customer support agent for Acme Corp. Be helpful, concise, and professional.",
    "tags": ["support"]
  },
  "personas": [
    {
      "name": "triage",
      "description": "Ticket triage and routing",
      "content": "Classify the support ticket and suggest a resolution or escalation path. Return JSON with fields: category, priority, suggested_action."
    }
  ],
  "pack": {
    "name": "support_pack",
    "description": "Support bot behavior",
    "hooks": {
      "new_ticket": {
        "persona": "triage",
        "template": "New support ticket from {{customer_name}}: {{message}}"
      }
    }
  }
}
EOF

# 3. Provision the pack and link it
starflask agents provision-pack ag_abc123 --file pack.json
# Pack provisioned and linked (hash: 3f8a1c...)

# 4. Activate the agent
starflask agents activate ag_abc123

You can also do this programmatically via the SDK (see below) or with the Rust SDK.

About

# Learn what Starflask is and how to build miniapps with it
starflask about    # or: starflask info

Shows how Starflask miniapps work — simple Vite webapps that perform AI agentic workflows purely through the Starflask API, with all agent config done via this CLI.

SDK (Programmatic Usage)

The starflask package also exports a Starflask class for use in Node.js scripts and backends.

npm install starflask

import { Starflask } from "starflask";

const sf = new Starflask({
  apiKey: process.env.STARFLASK_API_KEY,
  baseUrl: "https://starflask.xyz/api",
});

Query

Send a chat message to an agent and wait for the response:

// Simple query — uses the agent's soul prompt
const session = await sf.query(agentId, "What can you do?");
console.log(session.result);

// Query with a specific persona
const session = await sf.query(agentId, "Design a retro game UI palette", {
  persona: "palette_generator_reactive",
});

When you specify a persona, the agent's soul prompt is still used as the base system context, but the named persona's prompt is appended — giving the agent a specific behavioral mode for that query.

Hooks

For structured workflows where an agent pack defines event-specific persona templates with variable substitution:

// Fire and wait for completion
const session = await sf.fireHookAndWait(agentId, "generate_palette", {
  premise: "sunset over the ocean",
});

// Fire without waiting
const session = await sf.fireHook(agentId, "heartbeat", {});

Packs

Provision a pack to define an agent's soul, personas, and hooks:

const result = await sf.provisionPack(agentId, {
  soul: {
    name: "my_agent",
    description: "A helpful assistant",
    content: "You are a helpful assistant.",
    tags: ["assistant"],
  },
  personas: [
    {
      name: "default",
      description: "Default persona",
      content: "Respond concisely and helpfully.",
    },
  ],
  pack: {
    name: "my_pack",
    description: "My agent pack",
    hooks: {
      greet: {
        persona: "default",
        template: "Say hello to {{name}}.",
      },
    },
  },
});
console.log(result.content_hash);

Provisioning is idempotent — same content returns the same hash. Updated content replaces the agent's existing pack.

Other methods

sf.listAgents()
sf.createAgent({ name: "my-agent" })
sf.getAgent(agentId)
sf.setAgentActive(agentId, true)
sf.provisionPack(agentId, packDefinition)
sf.listSessions(agentId)
sf.getSession(agentId, sessionId)
sf.listIntegrations(agentId)
sf.listTasks(agentId)
sf.createTask(agentId, { name: "Daily check", hook_event: "heartbeat", schedule: "0 9 * * *" })
sf.getSubscriptionStatus()

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+