GitHub - withoneai/cli: A command-line tool to give your agents access to any app, create workflows and manage your One account.

One CLI

Website · Docs · Dashboard · Changelog · X · LinkedIn

One gives your AI agent authenticated access to 250+ platforms - Gmail, Slack, Shopify, HubSpot, Stripe, Notion, and everything else - through a single interface. No API keys to juggle, no OAuth flows to build, no request formats to memorize. Connect a platform once, and your agent can search for actions, read the docs, and execute API calls in seconds.

Install

npx @withone/cli@latest init

Or install globally:

npm install -g @withone/cli
one init

one init walks you through setup: enter your API key, pick your AI agents, and you're done. The MCP server gets installed automatically.

Requires Node.js 18+.

Quick start

# Connect a platform
one add gmail

# See what you're connected to
one list

# Search for actions you can take
one actions search gmail "send email" -t execute

# Read the docs for an action
one actions knowledge gmail <actionId>

# Execute it
one actions execute gmail <actionId> <connectionKey> \
  -d '{"to": "jane@example.com", "subject": "Hello", "body": "Sent from my AI agent"}'

That's it. Five commands to go from zero to sending an email through Gmail's API - fully authenticated, correctly formatted, without touching a single OAuth token.

Multi-step flows

Chain actions across platforms into reusable workflows:

# Create a flow that looks up a Stripe customer and sends a Gmail welcome email
one flow create welcome-customer --definition '{
  "key": "welcome-customer",
  "name": "Welcome New Customer",
  "version": "1",
  "inputs": {
    "stripeKey": { "type": "string", "required": true, "connection": { "platform": "stripe" } },
    "gmailKey": { "type": "string", "required": true, "connection": { "platform": "gmail" } },
    "email": { "type": "string", "required": true }
  },
  "steps": [
    { "id": "find", "name": "Find customer", "type": "action",
      "action": { "platform": "stripe", "actionId": "<actionId>", "connectionKey": "$.input.stripeKey",
        "data": { "query": "email:'\''{{$.input.email}}'\''" } } },
    { "id": "send", "name": "Send email", "type": "action",
      "if": "$.steps.find.response.data.length > 0",
      "action": { "platform": "gmail", "actionId": "<actionId>", "connectionKey": "$.input.gmailKey",
        "data": { "to": "{{$.input.email}}", "subject": "Welcome!", "body": "Thanks for joining." } } }
  ]
}'

# Validate it
one flow validate welcome-customer

# Run it - connection keys auto-resolve if you have one connection per platform
one flow execute welcome-customer -i email=jane@example.com

Workflows are stored as JSON at .one/flows/<key>.flow.json and support conditions, loops, while loops, parallel steps, transforms, sub-flows, pagination, bash steps, and more. Run one guide flows for the full reference.

How it works

Your AI Agent
    ↓
  One CLI
    ↓
  One API (api.withone.ai/v1/passthrough)
    ↓
  Gmail / Slack / Shopify / HubSpot / Stripe / ...

Every API call routes through One's passthrough proxy. One injects the right credentials, handles rate limiting, and normalizes responses. You never see or manage raw OAuth tokens - your connection key is all you need.

Commands

`one init`

Set up your API key and install the MCP server into your AI agents.

one init

Supports Claude Code, Claude Desktop, Cursor, Windsurf, Codex, and Kiro. Installs globally by default, or per-project with -p so your team can share configs (each person uses their own API key).

If you've already set up, one init shows your current status and lets you update your key, install to more agents, or reconfigure.

Flag	What it does
`-y`	Skip confirmations
`-g`	Install globally (default)
`-p`	Install for current project only

`one add <platform>`

Connect a new platform via OAuth.

one add shopify
one add hub-spot
one add gmail

Opens your browser, you authorize, done. The CLI polls until the connection is live. Platform names are kebab-case - run one platforms to see them all.

`one list`

List your active connections with their status and connection keys.

one list

  ● gmail       operational   live::gmail::default::abc123
  ● slack       operational   live::slack::default::def456
  ● shopify     operational   live::shopify::default::ghi789

You need the connection key (rightmost column) when executing actions.

`one platforms`

Browse all 200+ available platforms.

one platforms              # all platforms
one platforms -c "CRM"     # filter by category
one platforms --json       # machine-readable output

`one actions search <platform> <query>`

Search for API actions on a connected platform using natural language.

one actions search shopify "list products"
one actions search hub-spot "create contact" -t execute
one actions search gmail "send email"

Returns the top 5 matching actions with their action IDs, HTTP methods, and paths. Use -t execute when you intend to run the action, or -t knowledge (default) when you want to learn about it or write code against it.

`one actions knowledge <platform> <actionId>`

Get the full documentation for an action - parameters, validation rules, request/response structure, examples, and the exact API request format.

one actions knowledge shopify 67890abcdef

Always read the knowledge before executing. It tells you exactly what parameters are required, what format they need, and any platform-specific quirks.

`one actions execute <platform> <actionId> <connectionKey>`

Execute an API action on a connected platform.

# Simple GET
one actions execute shopify <actionId> <connectionKey>

# POST with data
one actions execute hub-spot <actionId> <connectionKey> \
  -d '{"properties": {"email": "jane@example.com", "firstname": "Jane"}}'

# With path variables
one actions execute shopify <actionId> <connectionKey> \
  --path-vars '{"order_id": "12345"}'

# With query params
one actions execute stripe <actionId> <connectionKey> \
  --query-params '{"limit": "10"}'

Option	What it does
`-d, --data <json>`	Request body (POST, PUT, PATCH)
`--path-vars <json>`	Replace `{variables}` in the URL path
`--query-params <json>`	Query string parameters
`--headers <json>`	Additional request headers
`--form-data`	Send as multipart/form-data
`--form-url-encoded`	Send as application/x-www-form-urlencoded
`--dry-run`	Show the request without executing it

`one guide [topic]`

Get the full CLI usage guide, designed for AI agents that only have the binary (no MCP, no IDE skills).

one guide                 # full guide (all topics)
one guide overview        # setup, --agent flag, discovery workflow
one guide actions         # search, knowledge, execute workflow
one guide flows           # multi-step API workflows

one --agent guide         # full guide as structured JSON
one --agent guide flows   # single topic as JSON

Topics: overview, actions, flows, all (default).

In agent mode (--agent), the JSON response includes the guide content and an availableTopics array so agents can discover what sections exist.

`one flow create [key]`

Create a workflow from a JSON definition. Workflows are saved to .one/flows/<key>.flow.json.

# From a --definition flag
one flow create welcome-customer --definition '{"key":"welcome-customer","name":"Welcome","version":"1","inputs":{},"steps":[]}'

# From stdin
cat flow.json | one flow create

# Custom output path
one flow create my-flow --definition '...' -o ./custom/path.json

Option	What it does
`--definition <json>`	Workflow definition as a JSON string
`-o, --output <path>`	Custom output path (default: `.one/flows/<key>.flow.json`)

`one flow execute <key>`

Execute a workflow by key or file path. Pass inputs with repeatable -i flags.

# Execute with inputs
one flow execute welcome-customer \
  -i customerEmail=jane@example.com

# Dry run - validate and show plan without executing
one flow execute welcome-customer --dry-run -i customerEmail=jane@example.com

# Verbose - show each step as it runs
one flow execute welcome-customer -v -i customerEmail=jane@example.com

Connection inputs with a connection field in the workflow definition are auto-resolved when the user has exactly one connection for that platform.

Press Ctrl+C during execution to pause - the run can be resumed later with one flow resume <runId>.

Option	What it does
`-i, --input <name=value>`	Input parameter (repeatable)
`--dry-run`	Validate and show execution plan without running
`--mock`	With `--dry-run`: execute transforms/code with mock API responses
`--allow-bash`	Allow bash step execution (disabled by default for security)
`-v, --verbose`	Show full request/response for each step

`one flow list`

List all workflows saved in .one/flows/.

one flow list

`one flow validate <key>`

Validate a workflow JSON file against the schema.

one flow validate welcome-customer

`one flow resume <runId>`

Resume a paused or failed workflow run from where it left off.

one flow resume abc123

`one flow runs [flowKey]`

List workflow runs, optionally filtered by workflow key.

one flow runs                    # all runs
one flow runs welcome-customer   # runs for a specific workflow

`one config`

Configure access control for the MCP server. Optional - full access is the default.

one config

Setting	Options	Default
Permission level	`admin` / `write` / `read`	`admin`
Connection scope	All or specific connections	All
Action scope	All or specific action IDs	All
Knowledge-only mode	Enable/disable execution	Off

Settings propagate automatically to all installed agent configs.

The workflow

The power of One is in the workflow. Every interaction follows the same pattern:

one list                    → What am I connected to?
one actions search          → What can I do?
one actions knowledge       → How do I do it?
one actions execute         → Do it.

This is the same workflow whether you're sending emails, creating CRM contacts, processing payments, managing inventory, or posting to Slack. One pattern, any platform.

For multi-step workflows that chain actions across platforms:

one actions knowledge       → Learn each action's schema
one flow create             → Define the workflow as JSON
one flow validate           → Check it
one flow execute            → Run it

Workflows support conditions, loops, while loops, parallel execution, transforms, code steps, sub-flows, pagination, bash steps, and file I/O. Run one guide flows for the full schema reference and examples.

For AI agents

If you're an AI agent with only the one binary (no MCP server or IDE skills), start with one --agent guide to get the full usage guide as structured JSON. This teaches you the complete workflow, JSON schemas, selector syntax, and more - everything you need to bootstrap yourself.

If you're an AI agent using the One MCP server, the tools map directly:

MCP Tool	CLI Command
`list_one_integrations`	`one list` + `one platforms`
`search_one_platform_actions`	`one actions search`
`get_one_action_knowledge`	`one actions knowledge`
`execute_one_action`	`one actions execute`

The workflow is the same: list → search → knowledge → execute. Never skip the knowledge step - it contains required parameter info and platform-specific details that are critical for building correct requests.

MCP server installation

one init handles this automatically. Here's where configs go:

Agent	Global	Project
Claude Code	`~/.claude.json`	`.mcp.json`
Claude Desktop	Platform-specific app support dir	-
Cursor	`~/.cursor/mcp.json`	`.cursor/mcp.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`	-
Codex	`~/.codex/config.toml`	`.codex/config.toml`
Kiro	`~/.kiro/settings/mcp.json`	`.kiro/settings/mcp.json`

Project configs can be committed to your repo. Each team member runs one init with their own API key.

Development

npm run dev        # watch mode
npm run build      # production build
npm run typecheck  # type check

Name		Name	Last commit message	Last commit date
Latest commit History 79 Commits
.github/workflows		.github/workflows
bin		bin
skills		skills
src		src
test		test
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
test-flow-features.ts		test-flow-features.ts
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

One CLI

Install

Quick start

Multi-step flows

How it works

Commands

`one init`

`one add <platform>`

`one list`

`one platforms`

`one actions search <platform> <query>`

`one actions knowledge <platform> <actionId>`

`one actions execute <platform> <actionId> <connectionKey>`

`one guide [topic]`

`one flow create [key]`

`one flow execute <key>`

`one flow list`

`one flow validate <key>`

`one flow resume <runId>`

`one flow runs [flowKey]`

`one config`

The workflow

For AI agents

MCP server installation

Development

About

Uh oh!

Releases 10

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

One CLI

Install

Quick start

Multi-step flows

How it works

Commands

one init

one add <platform>

one list

one platforms

one actions search <platform> <query>

one actions knowledge <platform> <actionId>

one actions execute <platform> <actionId> <connectionKey>

one guide [topic]

one flow create [key]

one flow execute <key>

one flow list

one flow validate <key>

one flow resume <runId>

one flow runs [flowKey]

one config

The workflow

For AI agents

MCP server installation

Development

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases 10

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`one init`

`one add <platform>`

`one list`

`one platforms`

`one actions search <platform> <query>`

`one actions knowledge <platform> <actionId>`

`one actions execute <platform> <actionId> <connectionKey>`

`one guide [topic]`

`one flow create [key]`

`one flow execute <key>`

`one flow list`

`one flow validate <key>`

`one flow resume <runId>`

`one flow runs [flowKey]`

`one config`

Packages