> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getpostchi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Actions

> Run standalone JavaScript scripts on demand to automate multi-step workflows.

Quick Actions are standalone scripts that aren't tied to any specific request. You run them manually from the actions panel whenever you need them. They're ideal for workflows that span multiple requests — like logging in and saving a token, seeding test data, or resetting state between test runs.

## File location

Store Quick Actions as `.action.js` files inside your project's `actions/` folder:

```text theme={null}
my-project/
  actions/
    login.action.js
    seed-data.action.js
  requests/
    ...
```

## Available context

Postchi injects these variables into every Quick Action:

| Variable                             | Type     | Description                                                                                        |
| ------------------------------------ | -------- | -------------------------------------------------------------------------------------------------- |
| `env`                                | object   | All active environment variables and secrets as string key-value pairs. Read-only.                 |
| `fetch`                              | function | The global `fetch` function.                                                                       |
| `setEnvironmentVariable(key, value)` | function | Saves a variable to the active environment in `environments.cenv`.                                 |
| `setSecret(key, value)`              | function | Saves a secret to the active environment in `secrets.cenv`.                                        |
| `executeRequest(relativePath)`       | function | Executes a request file from your `requests/` folder by relative path. Returns a `ScriptResponse`. |

### `executeRequest` return value

`executeRequest` returns a `ScriptResponse` object:

| Property  | Type           | Description                                 |
| --------- | -------------- | ------------------------------------------- |
| `status`  | number         | HTTP status code                            |
| `headers` | object         | Response headers as `{ name: value }` pairs |
| `body`    | string \| null | Response body as a string, or `null`        |

<Note>
  The path you pass to `executeRequest` is relative to your `requests/` folder — for example, `'auth/login.chttp'` resolves to `requests/auth/login.chttp`.
</Note>

## Examples

### Log in and save the auth token

```javascript theme={null}
// Execute the login request and capture the auth token
const response = await executeRequest('auth/login.chttp');
if (response.status === 200) {
  const data = JSON.parse(response.body);
  setSecret('api_token', data.token);
  console.log('Logged in successfully');
} else {
  throw new Error('Login failed: ' + response.status);
}
```

### Fetch an external value and save it

```javascript theme={null}
// Pull a config value from an external source
const res = await fetch('https://config.example.com/api-version');
const data = await res.json();
setEnvironmentVariable('api_version', data.version);
```

### Chain multiple requests

```javascript theme={null}
// Log in, then seed some test data
const loginResponse = await executeRequest('auth/login.chttp');
const loginData = JSON.parse(loginResponse.body);
setSecret('api_token', loginData.token);

const seedResponse = await executeRequest('admin/seed-users.chttp');
if (seedResponse.status !== 201) {
  throw new Error('Seeding failed: ' + seedResponse.status);
}
console.log('Test data seeded successfully');
```

## Running a Quick Action

<Steps>
  <Step title="Open the actions panel">
    Click the **Actions** section in the sidebar to see all `.action.js` files in your project.
  </Step>

  <Step title="Select an action">
    Click the action you want to run.
  </Step>

  <Step title="Run it">
    Click the run button. Postchi executes the script and applies any `setEnvironmentVariable` or `setSecret` calls immediately.
  </Step>
</Steps>

## Error handling

<Warning>
  If a Quick Action throws an error, Postchi shows the error message and does not apply any mutations from that run. Use `throw new Error(...)` to surface meaningful error messages when something goes wrong.
</Warning>