hyper-cli

# Hyper CLI 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. ## Requirements - **Hyper MCP configured for the workspace.** [https://app.hyperfx.ai/mcp](https://app.hyperfx.ai/mcp) - **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. - **Hyper CLI installed and authenticated.** Verify with `hyperai info`. If `hyperai info` fails, stop and tell the user to authenticate the CLI before calling tools. ## Tool surface | Need | Command | | --- | --- | | 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. ## Connected accounts 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: ```bash 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.