# 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. ```bash swy exec ``` For example: ```bash 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. ```bash swy exec github.issues.create \ --input repo=my-org/my-repo \ --input title="Login page bug" ``` Inputs are passed with these flags, each of which can be repeated: | Flag | Use | |---|---| | `--input key=value` | Any input the tool defines | | `--param key=value` | A query parameter | | `--header key=value` | A request header | | `--body file.json` | The request body, as a JSON file or inline JSON | | `--tenant ` | Run the call for one end user of your app, with their own connected account (see [Multi-tenant apps](/guides/multi-tenant/)) | | `--tenant-label ` | How approvers see that end user, e.g. `"Alice Smith (alice@acme.com)"`. Needs `--tenant`; shown only in approval messages | Fields the API expects in the request body can be given either way: `--input amount=1000` and `--body '{"amount":1000}'` send the same request. When both give the same field, `--input` wins. Before executing the request, Swytchcode validates the inputs against the tool's schema to ensure the request is complete and correctly formatted. You don't pass credentials as inputs. Once a provider is connected, Swytchcode adds its credential itself, including for tools whose schema lists a `token` or API-key input (see [Managed Authentication](/guides/managed-authentication/)). 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: ```bash echo '{"repo": "my-org/my-repo", "title": "Login page bug"}' | swy exec github.issues.create ``` --- ## Execute by intent `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: ```bash 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. ```text 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. ```bash 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 method - 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`. - **`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](/reference/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. ```json { "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` | Invalid input or validation error, or the provider's [base URL is not set](/configuration/manifest-json/#providers-on-your-own-instance) | | `2` | Tool not found | | `3` | Authentication failed | | `4` | The request couldn't be completed (network error or timeout), or the response couldn't be read | | `5` | Internal error | | `6` | Blocked by a policy (or its response was withheld by one) | | `7` | Waiting for [human approval](/policies/human-approval/) | | `130` | Interrupted (Ctrl+C) | A provider that answers with an error status (4xx or 5xx) still exits `0`: the JSON output carries `status_code`, `error_category`, and `retryable`. For common failure modes and how to fix them, see the [Troubleshooting](/reference/troubleshooting/) reference. --- ## Best practices - Test new methods 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. ## Related Pages - [Tools](https://docs.swytchcode.com/cli/tools/) - Learn how to enable and manage the methods available to your project. - [Execution Pipeline](https://docs.swytchcode.com/guides/execution-pipeline/) - Understand how every request flows through authentication, policy evaluation, and execution. - [Authentication](https://docs.swytchcode.com/cli/authentication/) - Learn how Swytchcode securely resolves provider credentials during execution. - [Policy Rules](https://docs.swytchcode.com/policies/policy-rules/) - Define runtime policies to control and protect tool execution. - [CLI Overview](https://docs.swytchcode.com/cli/overview/) - Explore the core concepts and architecture of the Swytchcode CLI. - [Troubleshooting](https://docs.swytchcode.com/reference/troubleshooting/) - Diagnose exit codes and common execution failures.