Execute Tools

Once you’ve installed an integration, enabled the required tools, and authenticated your accounts, you’re ready to execute tools.

Every tool execution goes through the Swytchcode CLI, which validates the request, applies your project configuration, and executes the corresponding API on your behalf.

Whether you’re using the CLI directly, an AI editor, or a runtime SDK, every execution follows the same execution pipeline.

Execute a tool

Use the exec command to execute any enabled tool.

swy exec <canonical_id>

For example:

swy exec github.issues.create

If the tool requires additional input, the CLI will prompt you or accept values through command line arguments, depending on the command.

Only tools that have been added to your project can be executed.

Passing inputs

Most tools require one or more input parameters.

For example, creating a GitHub issue requires a repository name and a title.

swy exec github.issues.create \
  --repo my-org/my-repo \
  --title "Login page bug"

Before executing the request, Swytchcode validates the inputs against the tool’s schema to ensure the request is complete and correctly formatted.

For tools with several inputs, or when you’re calling exec from a script, it’s often cleaner to pipe a JSON payload over stdin instead of listing flags:

echo '{"repo": "my-org/my-repo", "title": "Login page bug"}' | swy exec github.issues.create

exec is the single execution path for both known and unknown tools. Pass a canonical ID for direct execution, or a plain-English intent (no dot in the string) to have Swytchcode search for a matching tool first:

swy exec "create a github issue"

On a TTY, this runs the same semantic search as swy discover and shows an interactive picker so you can confirm the right tool before it runs. In non-interactive contexts (scripts, CI, agents), prefer resolving the canonical ID with swy discover --select or swy info ahead of time so execution doesn’t block on a prompt.

Execution lifecycle

Every execution follows the same flow.

Execute Tool
      │
      ▼
Validate Input
      │
      ▼
Execute Request
      │
      ▼
Return Response

This process is identical regardless of whether the request comes from the CLI, an AI editor, or a runtime SDK.

Preview a request

If you want to inspect a request before it is sent, use a dry run.

swy exec github.issues.create --dry-run

A dry run performs all validation steps without making the actual API request.

This is useful when:

Testing a new workflow
Verifying input values
Checking project configuration
Debugging execution issues

Demo and explain modes

Two other modes are useful while you’re still exploring a tool, before you’re ready to call the real API:

demo runs the tool against simulated responses instead of the live API - no auth or API keys required. This is the same mechanism behind swy demo stripe and swy demo fintech-compliance.
explain describes what a call would do in plain language without executing it or contacting the API, useful for reviewing an AI agent’s intended action before approving it.

These, along with dry_run, are exposed identically through the swytchcode_exec MCP tool - see the MCP Reference for how AI clients invoke them.

Understanding responses

Every execution returns a structured response.

A successful response contains the result returned by the target API.

{
  "success": true,
  "result": {
    "id": 123,
    "title": "Login page bug"
  }
}

If execution fails, the CLI returns an error describing what went wrong.

Exit codes

Swytchcode returns standard exit codes, making it easy to integrate into scripts and CI/CD pipelines.

Exit Code	Description
`0`	Execution completed successfully
`1`	Execution failed
`2`	Invalid input or validation error
`3`	Authentication failed
`4`	Execution blocked by policy
`5`	Tool not found

For common failure modes and how to fix them, see the Troubleshooting reference.

Best practices

Test new workflows with --dry-run before executing them.
Pass all required inputs to avoid validation errors.
Handle CLI exit codes when using automation or CI/CD.
Execute only tools that are required for your application.
Review execution errors before retrying failed requests.

The following pages provide additional context on how tool execution works and how to configure it for production use.

Tools

Learn how to enable and manage the methods and workflows available to your project.

Execution Pipeline

Understand how every request flows through authentication, policy evaluation, and execution.

Authentication

Learn how Swytchcode securely resolves provider credentials during execution.

Policy Rules

Define runtime policies to control and protect tool execution.

CLI Overview

Explore the core concepts and architecture of the Swytchcode CLI.

Troubleshooting

Diagnose exit codes and common execution failures.