agentport-cli

AgentPort: CLI interface

Read agentport-overview first. This skill covers how to drive AgentPort through the ap command-line tool when your runtime can run shell commands but doesn't speak MCP directly.

Prerequisites

• ap is installed and on PATH.
• The user has already authenticated the CLI against their AgentPort instance (ap auth login). You can check this with ap auth status.

If ap auth status reports auth_mode: none or the email field is blank, stop and ask the human to run ap auth login. Do not try to authenticate on their behalf.

Output format

Every command accepts -o json|toon|human. For programmatic use always pass -o json — it produces stable, machine-readable output. The default (human) is for terminal use and is not safe to parse.

The call flow

When you need to accomplish something via a third-party service, work through these steps in order. Do not skip ahead — each step answers a question you need answered before the next one makes sense.

1. Check if the integration is already installed

ap integrations list --installed -o json

This returns the integrations the user has already connected. Look for the integration_id you need (e.g. github, resend, slack). Each row also has a connected field — only connected: true integrations are usable.

2a. Integration is installed and connected → list its tools

ap tools list --integration <id> -o json

Each tool row has tool_name, description, and mode. The mode field tells you the approval policy: auto_approve, require_approval, or denied.

Skim the descriptions to find the tool(s) you want. If the descriptions don't give you enough to decide, describe them individually.

2b. Integration is not installed → ask the human

If the required integration is not in the installed list, do not try to install it yourself. Fetch the available list:

ap integrations list --available -o json

Confirm the integration exists, then tell the human what you need. A good message looks like:

I'd like to use the github integration to open that issue, but it isn't connected yet. Can I connect to it via AgentPort and run the authentication flow? You can also run this yourself with ap integrations add github.

Wait for the human to confirm before proceeding. Don't run ap integrations add on their behalf — the install flow is interactive (OAuth browser redirect or token paste) and needs a human at the keyboard.

3. Describe the tool before you call it

Before calling any tool, fetch its parameter schema:

ap tools describe --integration <id> --tool <tool_name> -o json

This returns the tool's inputSchema — a JSON Schema describing every parameter, which are required, their types, enums, and descriptions. Do not guess parameter names or shapes. If a field is listed in required, you must provide it. If it's optional, omit it unless you have a concrete value.

4. Call the tool

ap tools call --integration <id> --tool <tool_name> --args '<json>' --info '<why>' -o json

The --args value must be valid JSON that conforms to the inputSchema you just fetched. Always include --info — see the next section for what to put in it.

Always explain the call with --info

--info is a free-text string that is not forwarded to the upstream tool. It is recorded in the audit log and shown to any human who reviews the call (especially on approval-gated tools). Include it on every call.

A good --info answers two questions for a reviewer who sees the call without your conversation context:

1. What are you trying to do at the level of intent — "refund the duplicate charge Alice flagged", not "call create_refund".
2. Why now — the reason this call is happening at this moment, especially when acting on someone's behalf.

One sentence is usually enough.

Make opaque IDs verifiable

Many tool arguments are vendor IDs that mean nothing on their own: cus_OaBc…, Gmail message IDs, PostHog dashboard IDs, Slack channel IDs, Stripe invoice IDs. A reviewer cannot safely approve a call whose target is only identified by a random-looking string.

When an argument is an opaque ID, make it verifiable inside --info:

• Include a human-readable label alongside the ID (name, email, subject, title).
• Paste a link the reviewer can click to confirm what the ID refers to, when a public URL exists. Examples:
  • Stripe customer cus_OaBc… → https://dashboard.stripe.com/customers/cus_OaBc…
  • PostHog dashboard 42 → https://us.posthog.com/dashboard/42
  • GitHub issue #417 in owner/repo → https://github.com/owner/repo/issues/417
  • Gmail message <id> → https://mail.google.com/mail/u/0/#inbox/<id>
• If you don't have a clean URL, at minimum name the thing in words: customer Alice Jordan (cus_OaBc…).

Do not fabricate URLs you aren't sure are valid — a wrong link is worse than none. If you can't confidently link the ID, describe it instead.

Example:

ap tools call --integration stripe --tool create_refund \
  --args '{"charge": "ch_3ObC…"}' \
  --info "Refunding the duplicate \$49 charge for customer Alice Jordan (cus_OaBc…, https://dashboard.stripe.com/customers/cus_OaBc…) that she flagged in support ticket #812." \
  -o json

Handling the three outcomes

Success

ap tools call exits 0 and prints the tool's result on stdout. Parse and use.

Approval required

ap tools call exits with code 2 and writes Approval required: <url> to stderr. Treat this as a stop condition. Follow the approval handling described in agentport-overview — share the URL with the human, wait for confirmation, then retry the identical command with the identical --args. Changing the args invalidates the pending approval.

Denied

ap tools call exits with code 1 and writes Denied: … to stderr. There is no path forward — do not retry, do not try a different tool to reach the same outcome.

Quick reference

Goal	Command
Am I logged in?	ap auth status -o json
What's installed?	ap integrations list --installed -o json
What's available?	ap integrations list --available -o json
What tools does X expose?	ap tools list --integration <id> -o json
What does tool Y take?	ap tools describe --integration <id> --tool <name> -o json
Run tool Y	ap tools call --integration <id> --tool <name> --args '<json>' --info '<why>' -o json

What not to do

• Don't run ap integrations add or ap integrations remove without the user's explicit instruction — installation is a user-authentication flow.
• Don't guess tool parameter names. ap tools describe is cheap; use it.
• Don't strip the -o json flag when automating; parsing the human output is brittle.
• Don't retry on exit 1 (denied) or fabricate workarounds. Ask the human.
• Don't omit --info, and don't fill it with generic filler ("calling tool"). Write a real sentence of intent.
• Don't pass opaque IDs in --args without also naming or linking them in --info so a reviewer can verify them.