---
# @generated by sylphx-gen. Do not edit.
title: "sylphx agents goals"
description: "The sylphx agents goals commands of Sylphx Agents: every verb, with its argument, its flags and a run line."
type: reference
product: agents
summary: "Every sylphx agents goals command: its argument, its flags and a run line."
updated: 2026-09-28
nav: false
---

The `goals` commands of Sylphx Agents, as the CLI spells them: the same
calls as [the `goals` API page](/docs/api/goals), typed for the
shell. [Install, sign in and the grammar](/docs/cli) are on the CLI index.

## create

Creates an optional objective owned by this Session, without an external Task. The operation_id keeps the original receipt beyond request replay expiry.

**CLI**

```bash
sylphx agents goals create --parent orgs/acme/projects/shop/envs/production/agent_sessions/agent-session --objective …
```

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session/goals` · scope `agents:sessions` · effect `write` · [Request, response and examples](/docs/api/goals/create)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--parent` | `string` | The parent to create in; defaults to the linked project or the key's scope. |
| `--objective` | `string` | The objective, nonempty and at most 4,000 characters. Required. |
| `--token-budget` | `int` | Omit unless the caller explicitly requests a positive token budget. |
| `--operation-id` | `string` | Caller-stable mutation identity, nonempty and at most 128 bytes. Required. |

## get

Reads the exact Goal, including its terminal receipt after a successor starts.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx agents goals get orgs/acme/projects/shop/envs/production/agent_sessions/agent-session/goals/goal
```

`GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session/goals/goal` · scope `agents:sessions` · effect `read` · [Request, response and examples](/docs/api/goals/get)

## settle

Settles only the named Goal/version with an observed environment receipt. Replaying operation_id returns its original receipt, never its successor.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx agents goals settle orgs/acme/projects/shop/envs/production/agent_sessions/agent-session/goals/goal
```

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session/goals/goal:settle` · scope `agents:sessions` · effect `write` · [Request, response and examples](/docs/api/goals/settle)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--expected-version` | `int` | The acceptance-contract version observed by the caller. Required. |
| `--state` | `enum` | Only COMPLETED and FAILED settle a Goal. Waiting is not success. Required. One of `working`, `waiting`, `completed`, `failed`. |
| `--receipt` | `json` | An actual observation at the delivered environment surface. Required. |
| `--operation-id` | `string` | Caller-stable mutation identity, nonempty and at most 128 bytes. Required. |

## control

Applies an explicit owner control to this exact Goal/version. Pause interrupts only its current execution; resume does not resolve a wait or clear observed usage. Amend changes only supplied objective/budget fields.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx agents goals control orgs/acme/projects/shop/envs/production/agent_sessions/agent-session/goals/goal
```

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session/goals/goal:control` · scope `agents:sessions` · effect `write` · [Request, response and examples](/docs/api/goals/control)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--expected-version` | `int` | The contract version observed by the owner. Required. |
| `--action` | `enum` | Explicit owner action. Only AMEND accepts objective/budget changes. Required. One of `pause`, `resume`, `amend`. |
| `--operation-id` | `string` | Caller-stable mutation identity, nonempty and at most 128 bytes. Required. |
| `--objective` | `string` | New objective, only when amending. Omission preserves the existing text. |
| `--token-budget` | `int` | New explicit token budget, only when amending. Omission preserves it. |
| `--clear-token-budget` | `bool` | Explicitly remove a budget when amending; incompatible with token_budget. |