---
title: CommandOptions
description: "The options of `command()`: the Repo Slot it runs in, how long it can run, how much of its output it keeps, its Effect secrets, and the commit it runs against."
---

# `CommandOptions`

Type, in `@jr2/orchestrator/src/effect.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.

```ts
type CommandOptions = {
  slot?: string;
  timeout?: Duration;
  tail?: number;
  env?: CommandEnv;
  pin?: boolean;
};
```

The options of `command()`: the Repo Slot it runs in, how long it can run, how much of its
output it keeps, its Effect secrets, and the commit it runs against.

**Fields**

- `slot` (optional): `string`

  The Repo Slot whose Worktree is the working directory of the command. Write it only when the
  Workspace has more than one Repo Slot. In a Workspace with no Repo Slot, the command starts in
  `/work`, the folder that the steps of the Workspace share.

  The command starts in the root of that Worktree. To run it in a subfolder, give the path as an
  argument, or write `["sh", "-c", "cd <dir> && <program>"]`.

  When it starts, it refuses:
  - no `slot` under a Workspace with more than one Repo Slot: `command "<slot>" runs under a
    Workspace carrying more than one Repo Slot (<slots>) and names none — say which Worktree it
    runs in: command(argv, { slot: "<slot>" }) (ADR-0051)`. When `env` names an Effect secret,
    the text is `command "<slot>" runs under a Workspace carrying more than one Repo Slot
    (<slots>) — say which: { slot: "<slot>" } (ADR-0051)`.
  - with an Effect secret in `env`, a Workspace with no Repo Slot: `command "<slot>" runs under
    a Workspace with no Repo Slot: a command with an Effect secret runs against one commit of a
    Repo Slot's branch, and there is none — declare a Repo Slot, or name no secret in its env, and
    it runs in /work beside the Agent (ADR-0051)`.
  - a `slot` that the Workspace does not have: `command "<slot>" names Repo Slot "<name>", which
    its Workspace does not carry (<slots>)`.
- `timeout` (optional): [`Duration`](type-duration.md)

  How long the command can run: a number and a unit, such as `"90s"`, `"10m"` or `"1h"`.
  Default `"10m"`. When the time ends, jr2 kills the process group, and the output is
  `timeout`. It refuses a value that is not a positive duration: `command: timeout "<timeout>"
  is not a positive duration (like "90s", "10m", "1h")`.
- `tail` (optional): `number`

  The number of characters that `tail` keeps from the end of what the command wrote. Default
  4096.
- `env` (optional): [`CommandEnv`](type-commandenv.md)

  The environment variables of the command, each an Effect secret. `secret("x")` gives the
  value, and `secret("x").path` gives the path of a file that holds the value. When `env` names
  one, the command runs in the Sandbox Effector against one commit, not in the Worktree that the
  Agent changes. Without `env`, it runs in the Harness container, beside the Agent.

  It refuses a name that is not a variable name, and `PATH`, `HOME` and `TMPDIR`: ``command(argv,
  { env }): "<name>" is not a variable the author sets — PATH, HOME and TMPDIR are the
  Effector's (ADR-0067)``.
- `pin` (optional): `boolean`

  Only for a command whose `env` names an Effect secret. `true`: the input of the Effect names
  the commit to run against (`{ sha }`, a full commit id, for example one that a Gate approved).
  Default: the tip of the Agent's branch when the Effect starts.

  It refuses `pin: true` on a command that names no Effect secret: ``command(argv, { pin: true
  }) names no secret in its env: `pin` chooses the commit a credentialed command runs against in
  the Sandbox Effector, and a command that names no secret runs in the live Worktree (ADR-0067)
  — name its secret, command(argv, { env: { NAME: secret("x") }, pin: true }), or drop `pin` ``.

  When it starts, it refuses an input `sha` that is not a full commit id: `command "<slot>"
  (pin): its input's sha is not a full commit id`.