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

# Run Gloo Code from Scripts

> Use gloocode run to send Gloo Code a task from a script or a shell one-liner, with no terminal UI.

`gloocode run` sends one task to Gloo Code, prints the result, and exits. There is no terminal UI and no one to click Approve, so it suits scripts, one-off tasks, and anything you want to chain with other commands.

Gloo Code signs in with your Gloo account in the browser, and a run uses the profile you are signed in with. Install and sign in first: see [Installation & Setup](/gloocode/installation).

Use it when you want to:

* Fire off a single task without opening the TUI.
* Pipe a file or command output into Gloo Code.
* Call Gloo Code from a shell script or a Makefile.
* Read the results as JSON from another program.

For interactive work, start the [terminal UI](/gloocode/launch) instead.

## Run your first task

Pass your message after `run`:

```bash theme={null}
gloocode run "Explain what this project does"
```

Gloo Code works on the task, prints its replies as it goes, and exits when the turn is finished. Quote the message so your shell passes it as one argument.

## Choose where it runs

By default the run happens in your current folder. Use `--dir` to point it somewhere else:

```bash theme={null}
gloocode run --dir ~/projects/billing-service "Find and fix the failing test"
```

Paths you pass to `--file` are resolved from that folder.

## Choose a model and an agent

Gloo Code picks a model for you. To choose one yourself, pass `-m` (or `--model`) with a `gloo/<model-key>` name:

```bash theme={null}
gloocode run -m gloo/<model-key> "Summarize the last 10 commits"
```

If the name isn't a supported Gloo model, the run stops with an error before it starts. List the available models with `gloocode models --verbose`.

Use `--agent` to run as a specific primary agent, such as `plan`:

```bash theme={null}
gloocode run --agent plan "Outline how we could add rate limiting"
```

If the agent name doesn't exist, or it is a subagent rather than a primary agent, the run prints a warning and falls back to the default agent.

## Continue or fork a session

Each run starts a new session unless you ask it to pick one up:

| Flag | What it does |
| - | - |
| `-c`, `--continue` | Continue the most recent session |
| `-s`, `--session <id>` | Continue a specific session |
| `--fork` | Copy the session first and continue the copy. Use it together with `-c` or `-s` |

```bash theme={null}
gloocode run "Add tests for the parser"
gloocode run -c "Now handle the empty-input case"
gloocode run -c --fork "Try a different approach"
```

## Attach files

Use `-f` (or `--file`) to attach files to your message. Repeat it for more than one:

```bash theme={null}
gloocode run -f src/parser.ts -f docs/spec.md "Does the parser match the spec?"
```

If a file doesn't exist, the run exits with an error before sending anything.

## Pipe in input

When something is piped into `gloocode run`, it is appended to your message:

```bash theme={null}
cat spec.md | gloocode run "Implement this"
git diff main | gloocode run "Review this diff for bugs"
gloocode run < prompt.txt
```

You can also send only piped input with no message. If there is no message and nothing is piped in, the run exits with an error.

## Run a saved command

Use `--command` to run one of your saved slash commands. Whatever you put in the message is passed to the command as its arguments:

```bash theme={null}
gloocode run --command review "src/auth"
```

## Read the output as JSON

By default, `gloocode run` prints formatted, human-readable output. Add `--format json` and it prints a stream of JSON events, one per line, which is easy to read from a script:

```bash theme={null}
set -o pipefail
gloocode run --format json "Add a health check endpoint" | jq -c '{type, sessionID}'
```

Without `set -o pipefail`, a failed run can still leave the pipeline with exit status `0`, because the shell reports the status of `jq`.

Every line carries `type`, `timestamp`, and `sessionID`, plus a payload that depends on the type.

These event types appear in the stream:

| Event | When you get it |
| - | - |
| `step_start`, `step_finish` | A model step begins or ends. `step_finish` includes token counts |
| `text` | The agent finished a block of text |
| `tool_use` | A tool call finished. `part.state.status` is `completed` or `error` |
| `reasoning` | A thinking block finished. Only with `--thinking` |
| `subagent_tool_use` | A subagent's tool call finished. Only with `--subagent-tools` |
| `permission_asked`, `permission_replied` | A permission request was raised and answered |
| `safety_refused` | The run turned down an action that needed your approval, with the reason |
| `model_resolution`, `session_completion` | Which model was used for a step, and the end of the turn |
| `error` | The turn hit an error |

## Exit codes

| Code | Meaning |
| - | - |
| `0` | The agent finished its turn. |
| `1` | The turn ended in an error (a refused or failed request, an aborted turn), or the run couldn't start (bad arguments, a missing file or directory). |

A tool call that fails partway through doesn't make the run fail on its own, because the agent can recover and carry on. With `--format json`, failed tool calls show up as `tool_use` events with `part.state.status` set to `"error"`, and failed turns show up as `error` events.

## Permission prompts in a run

A script can't answer a prompt, so `gloocode run` answers for you: by default it **rejects** any permission request and keeps going. Work that stays inside your project mostly doesn't ask for permission in the first place, so many tasks run fine as they are. A request that does come up appears as a warning line, or as `permission_asked` and `permission_replied` events with `--format json`.

For a task that needs those requests approved, add `--unleashed` and `gloocode run` allows every prompt that no deny rule blocks:

```bash theme={null}
gloocode run --unleashed "Update the dependencies and fix anything that breaks"
```

`--unleashed` applies to that one run only. There is no setting to leave it on, so each run that skips prompts says so on its command line. Rules that deny still deny, because those are part of how the agent is set up.

> [!WARNING]
>
> `--unleashed` allows every prompt that no deny rule blocks, except the safety prompts that follow outside content: `gloocode run` still refuses those unless you allow them in Settings ▸ Safety. The agent can change or delete files and run commands without asking. Use it only in a scratch folder, a container, or a throwaway checkout, not on work you haven't committed. You are responsible for what it runs.

> [!TIP]
>
> For a first try, copy the project into a scratch folder and run there with `--dir`. You can look at the result, then keep it or throw it away.

If a safety setting turns an action down, the run prints the setting that would allow it. See [Safety settings](/gloocode/whats-new#safety-settings).

## From Claude Code and Codex

If you already script another coding agent, the move is one command:

| You use | In Gloo Code |
| - | - |
| `claude -p "task"` | `gloocode run "task"` |
| `codex exec "task"` | `gloocode run "task"` |

Both pages cover the rest of the move: [From Claude Code](/gloocode/migrate/from-claude-code) and [From Codex](/gloocode/migrate/from-codex).

## Next steps

> **[Migrate to Gloo Code](/gloocode/migrate/overview)**
>
> What carries over from other coding agents.

> **[Install Gloo Code](/gloocode/installation)**
>
> Install the CLI and sign in.

> **[Billing & Plans](/studio/billing#choosing-a-gloo-code-tier)**
>
> Tiers, seats, monthly allowance, and top-ups.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.