Skip to main content

CLI Reference

The fma command-line tool lets you manage agents, tools, and runs directly from your terminal.

Installation​

pip install fma

Configuration​

The CLI stores its configuration in ~/.config/fma/config.yaml.

Env variableDescriptionDefault
FLYMYAI_API_KEYAPI key (used when no key is saved locally)--
FLYMYAI_DSNBase URL overridehttps://backend.flymy.ai

Authentication​

Save your API key​

fma api-key set fly-abc123...

The key is written to ~/.config/fma/config.yaml and used for all subsequent commands.

Show current key​

fma api-key show
API key: fly-abc***23

The key is masked for security. You can also skip local storage entirely and export the key as an environment variable:

export FLYMYAI_API_KEY="fly-abc123..."

Agents​

Create an agent​

fma agents create --name "Web Researcher" \
  --goal "Search the web for {{ topic }} and return a summary with sources." \
  --tools 1,2
FlagRequiredDescription
--nameYesHuman-readable name
--goalYesInstructions (supports Handlebars templating)
--toolsNoComma-separated tool IDs to attach

List agents​

fma agents list

Get agent details​

fma agents get a1b2c3d4-...

Add --json-output for raw JSON:

fma agents get a1b2c3d4-... --json-output

Update an agent​

Only the flags you pass are changed; everything else stays the same.

fma agents update a1b2c3d4-... \
  --name "Updated Name" \
  --goal "New instructions." \
  --tools 1,2,3

Delete an agent​

fma agents delete a1b2c3d4-...

Run an agent​

fma agents run a1b2c3d4-...

By default, the command fires the run and exits immediately, printing the run ID.

FlagDescription
--streamStream execution events in real-time with colored output
--waitPoll until the run finishes, then print the result
--timeout 300Maximum wait time in seconds (default: 300)

Fire-and-forget (default):

$ fma agents run a1b2c3d4-...
Run #42 started.

Stream events:

$ fma agents run a1b2c3d4 --stream
Run #42 started

  [functions]  Functions for agent
  [tool]       Called tool tavily--search
  [tool]       Called tool system-utils--save_result

Status: completed
Result:
{
  "summary": "...",
  "sources": [...]
}

Wait for result:

$ fma agents run a1b2c3d4 --wait --timeout 120
Waiting for run #42... completed

{
  "summary": "...",
  "sources": [...]
}

Runs​

List recent runs​

fma runs list
fma runs list --limit 50

Get run details​

fma runs get 42
fma runs get 42 --json-output

Cancel a run​

fma runs cancel 42

Wait for a run to finish​

Polls the server until the run reaches a terminal state.

fma runs wait 42 --timeout 300 --poll 2.0
FlagDefaultDescription
--timeout300Maximum wait time in seconds
--poll2.0Polling interval in seconds

View run logs​

fma runs logs 42

Tools​

Browse the catalog​

List all tools available on the FlyMy.AI platform:

fma tools available

Filter by category:

fma tools available --filter development

List your configured tools​

fma tools list

Add a tool from the catalog​

fma tools add tavily

Configure a tool​

Walk through the configuration steps interactively:

fma tools configure 7

Or provide configuration as JSON in one shot:

fma tools configure 7 --response '{"TAVILY_API_KEY": "tvly-..."}'

Call a tool directly​

Invoke a specific action on a configured tool without running an agent:

fma tools call 7 --action search --args '{"query": "FlyMyAI agents"}'

Remove a tool​

fma tools remove 7

Complete workflow​

A start-to-finish example: authenticate, add a tool, create an agent, and run it with streaming output.

# 1. Save your API key
fma api-key set fly-abc123...

# 2. Browse available tools and add one
fma tools available
fma tools add tavily

# 3. Configure the tool (note the ID from the previous step)
fma tools configure 1 --response '{"TAVILY_API_KEY": "tvly-..."}'

# 4. Create an agent with the tool attached
fma agents create \
  --name "Research Assistant" \
  --goal "Research {{ topic }} thoroughly. Return a summary with key findings and sources." \
  --tools 1

# 5. Run the agent and stream the output
fma agents run a1b2c3d4-... --stream

Expected output:

Run #1 started

  [functions]  Functions for agent
  [tool]       Called tool tavily--search
  [tool]       Called tool system-utils--save_result

Status: completed
Result:
{
  "summary": "...",
  "sources": [...]
}

To check on the run later or view its logs:

fma runs get 1
fma runs logs 1