git:20260706.e7fcf13 to git:20260913.ec78ecf

- description: Use the Hyper CLI to run Hyper marketing skills from a terminal. Use when the user wants to use `hyperai`, inspect live tool schemas, translate MCP tool names from a skill into CLI commands, switch connected accounts, or run marketing tools outside an MCP-native agent host.

- Use `hyperai` to run Hyper tools from a terminal. This skill is a bridge for using the marketing skills in this repo through the CLI.

-

- Marketing skills usually name the MCP/raw tools, such as `gmail_messages_send` or `meta_ads_ad_accounts_list`. The CLI also exposes friendly aliases, such as `gmail messages send` or `meta-ads ad-accounts list`. Pick one surface per call.

- - **Required integrations connected** at [https://app.hyperfx.ai/apps](https://app.hyperfx.ai/apps). Use the sibling marketing skill to know which integrations are required.

- ## Tool surface

- | Confirm auth/workspace | `hyperai info` |

- | Find tools by intent or raw MCP name | `hyperai search "<intent or raw tool name>" --json --signature` |

- | Browse friendly aliases in a namespace | `hyperai describe <namespace>` |

- | Inspect a friendly alias schema | `hyperai describe <alias path> --parameters` |

- | Call a friendly alias | `hyperai call <alias path> --json '{...}'` |

- | Inspect a raw toolkit tool | `hyperai tools describe <toolkit> <tool_name> --parameters` |

- | Call a raw toolkit tool | `hyperai tools call <toolkit> <tool_name> --json '{...}'` |

- | List connected accounts | `hyperai tools list --connected` or `hyperai connections list` |

- | Switch active account | `hyperai connections use <toolkit> <auth-id>` |

-

- ## Critical rule: aliases vs raw tools

-

- Friendly alias path:

-

- ```bash

- hyperai describe gmail messages send --parameters

- hyperai call gmail messages send --json '{"to":"person@example.com","subject":"Hello","body":"Hi"}'

- ```

-

- Raw toolkit path:

-

- ```bash

- hyperai tools describe gmail gmail_messages_send --parameters

- hyperai tools call gmail gmail_messages_send --json '{"to":"person@example.com","subject":"Hello","body":"Hi"}'

- ```

-

- If a marketing skill says `gmail_messages_send`, that is a raw MCP/toolkit name. Either translate it with search:

-

- ```bash

- hyperai search "gmail_messages_send" --json --signature

- ```

-

- or call it through the raw toolkit surface:

-

- ```bash

- hyperai tools call gmail gmail_messages_send --json '{...}'

- ```

-

- Never assume `hyperai call gmail_messages_send` will work.

-

- ## Describe progression

-

- Use `describe` progressively. Start broad, then narrow to the exact alias before calling:

-

- ```bash

- hyperai describe gmail

- hyperai describe gmail messages send --parameters

- hyperai call gmail messages send --to person@example.com --subject "Hello" --body "Hi"

- ```

-

- For friendly aliases, use `hyperai describe <namespace>` and `hyperai describe <alias path> --parameters`. Do not use `hyperai tools describe gmail` for namespace browsing; `tools describe` is the raw toolkit form and needs both toolkit and raw tool name.

-

- ## Structured arguments

-

- Flags are safest for simple scalar fields:

-

- ```bash

- hyperai call gmail messages send --to person@example.com --subject "cli test" --body "this is a test"

- ```

-

- Use `--json` for arrays, objects, nested schemas, and model-specific tools. Do not pass arrays or objects as string flags unless the live schema explicitly says the field is a string.

-

- ```bash

- hyperai describe images generate nano-banana --parameters

- hyperai call images generate nano-banana \

- --json '{"requests":[{"prompt":"a cat wearing a propeller hat"}],"model":"pro"}'

- ```

-

- If validation says an object field was received as a string, retry with `--json` after re-reading `describe --parameters`.

- ## Workflow

- 1. Read the relevant marketing skill first, for example `meta-ads`, `cold-email-outreach`, `email-lifecycle`, or `analytics-insights`.

- 2. Use that skill for strategy, sequencing, safety rules, and required integrations.

- 3. For each tool named in the skill, resolve the live CLI command:

- - Try `hyperai search "<tool name or intent>" --json --signature`.

- - Prefer the returned `call_command` when available.

- - If no good alias exists, use `hyperai tools describe <toolkit> <tool_name>`.

- 4. Before calling, inspect the live schema:

- - Friendly alias: `hyperai describe <alias path> --parameters`.

- - Raw toolkit: `hyperai tools describe <toolkit> <tool_name> --parameters`.

- 5. Call with `--json` for structured inputs.

- 6. If validation fails, re-run the relevant `describe --parameters` command before retrying.

- List available connected accounts:

-

- ```bash

- hyperai tools list --connected

- hyperai connections list

- hyperai connections list gmail

- ```

-

- Set the active connection for future CLI calls:

-

- ```bash

- hyperai connections use gmail <auth-id>

- hyperai connections use meta_business <auth-id>

- ```

-

- Use `--auth-id <auth-id>` only for a one-off override.

-

- ## Examples

-

- Marketing skill names raw Gmail tool:

-

- ```text

- gmail_messages_list

- ```

-

- Resolve and call friendly alias:

-

- ```bash

- hyperai search "gmail_messages_list" --json --signature

- hyperai describe gmail messages list --parameters

- hyperai call gmail messages list --json '{"max_results":10}'

- ```

-

- Marketing skill names raw Meta tool:

-

- ```text

- meta_business_list_ad_accounts

- ```

-

- Resolve and call friendly alias:

-

- ```bash

- hyperai search "meta_business_list_ad_accounts" --json --signature

- hyperai describe meta-ads ad-accounts list --parameters

- hyperai call meta-ads ad-accounts list --json '{"detail":"id_only"}'

- ```

-

- Raw fallback:

-

- ```bash

- hyperai tools describe meta_business meta_business_list_ad_accounts --parameters

- hyperai tools call meta_business meta_business_list_ad_accounts --json '{"detail":"id_only"}'

- ```

- Image generation:

- ```bash

- # Default image generation alias accepts the prompt positionally.

- hyperai call images generate "a cat wearing a propeller hat" --quality draft --output json

- # Model-specific image tools often need JSON because their schema is nested.

- hyperai describe images generate nano-banana --parameters

- hyperai call images generate nano-banana \

- --json '{"requests":[{"prompt":"a cat wearing a propeller hat"}],"model":"pro"}' \

- --output json

- ```

- Meta ads performance:

- hyperai search "meta ads insights" --json --signature

- hyperai call meta-ads ad-accounts list --output json

- hyperai describe meta-ads insights get --parameters

- hyperai call meta-ads insights get --json '{"object_id":"act_<ad_account_id>","object_type":"account","date_range":"last_month"}'

- Always list ad accounts first when the user asks for account-level performance and did not provide an `act_...` account id.

-

- ## Rules

- - The live CLI schema wins over examples in any skill.

- - Marketing skills provide workflow judgment; `hyperai describe` provides executable arguments.

- - Prefer friendly aliases for normal use because they are easier for agents and humans.

- - Use raw `hyperai tools ...` when a skill gives an exact MCP tool name and no alias is obvious.

- - Do not invent toolkit IDs, tool names, or parameter names.