> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/dsx-air/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/dsx-air/_mcp/server.

# air_sdk.endpoints.node_instructions

Stub file for node instructions endpoint type hints.

## Classes

| Name                                                                                         | Description                                                               |
| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| [`ShellData`](#air_sdkendpointsnode_instructionsshelldata)                                   | Data structure for shell executor type (input for create).                |
| [`_FileDataRequired`](#air_sdkendpointsnode_instructions_filedatarequired)                   | Required fields for FileData.                                             |
| [`FileData`](#air_sdkendpointsnode_instructionsfiledata)                                     | Data structure for file executor type (input for create).                 |
| [`InitData`](#air_sdkendpointsnode_instructionsinitdata)                                     | Data structure for init executor type (input for create).                 |
| [`ShellDataResponse`](#air_sdkendpointsnode_instructionsshelldataresponse)                   | Data structure for shell executor type (returned from API).               |
| [`FileDataResponse`](#air_sdkendpointsnode_instructionsfiledataresponse)                     | Data structure for file executor type (returned from API).                |
| [`InitDataResponse`](#air_sdkendpointsnode_instructionsinitdataresponse)                     | Data structure for init executor type (returned from API).                |
| [`NodeInstruction`](#air_sdkendpointsnode_instructionsnodeinstruction)                       | Node instruction model representing an automation instruction for a node. |
| [`NodeInstructionEndpointAPI`](#air_sdkendpointsnode_instructionsnodeinstructionendpointapi) | API client for node instructions endpoints.                               |

## Module Contents

```python
class air_sdk.endpoints.node_instructions.ShellData
```

**Bases**: `typing.TypedDict`

Data structure for shell executor type (input for create).

```python
commands: list[str]
```

```python
class air_sdk.endpoints.node_instructions._FileDataRequired
```

**Bases**: `typing.TypedDict`

Required fields for FileData.

```python
files: list[dict[str, str]]
```

```python
class air_sdk.endpoints.node_instructions.FileData
```

**Bases**: `air_sdk.endpoints.node_instructions._FileDataRequired`

Data structure for file executor type (input for create).

Required: files - List of file dicts, each with 'path' and 'content' keys.
Optional: post\_commands - Shell commands to run after creating files.

```python
post_commands: list[str]
```

```python
class air_sdk.endpoints.node_instructions.InitData
```

**Bases**: `typing.TypedDict`

Data structure for init executor type (input for create).

```python
hostname: str
```

```python
class air_sdk.endpoints.node_instructions.ShellDataResponse
```

**Bases**: `air_sdk.endpoints.node_instructions.ShellData`

Data structure for shell executor type (returned from API).

```python
executor: Literal[shell]
```

```python
class air_sdk.endpoints.node_instructions.FileDataResponse
```

**Bases**: `air_sdk.endpoints.node_instructions._FileDataRequired`

Data structure for file executor type (returned from API).

Required: files - List of file dicts, each with 'path' and 'content' keys.
Optional: post\_commands - Shell commands to run after creating files.
Optional: executor - Executor type (added by API).

```python
post_commands: list[str]
```

```python
executor: Literal[file]
```

```python
class air_sdk.endpoints.node_instructions.InitDataResponse
```

**Bases**: `air_sdk.endpoints.node_instructions.InitData`

Data structure for init executor type (returned from API).

```python
executor: Literal[init]
```

```python
class air_sdk.endpoints.node_instructions.NodeInstruction
```

**Bases**: `air_sdk.air_model.AirModel`

Node instruction model representing an automation instruction for a node.

Node instructions are commands or automation scripts that can be executed
on simulation nodes. They support various executors and can be configured
to run again on rebuild.

```python
id: str
```

Unique identifier for the node instruction

```python
name: str
```

Human-readable name of the node instruction

```python
node: Node
```

Node this instruction belongs to

```python
data: ShellDataResponse | FileDataResponse | InitDataResponse
```

Instruction data (ShellData, FileData, or InitData)

```python
created: datetime.datetime
```

Timestamp when the node instruction was created

```python
modified: datetime.datetime
```

Timestamp when the node instruction was last modified

```python
state: str
```

Execution state (e.g., 'pending', 'running', 'completed', 'failed')

```python
run_again_on_rebuild: bool
```

Whether to re-run this instruction on simulation rebuild

```python
get_model_api() -> type[NodeInstructionEndpointAPI]
```

```python
model_api: NodeInstructionEndpointAPI
```

```python
update(
    *,
    name: str | None = ...,
    run_again_on_rebuild: bool | None = ...
) -> None
```

Update the node instruction's properties.

**Parameters:**

* `name` – New name for the node instruction
* `run_again_on_rebuild` – Whether to re-run the instruction on simulation rebuild

**Example:**

```python
>>> instruction = api.node_instructions.get('instruction-id')
>>> instruction.update(name='New Name', run_again_on_rebuild=True)
```

```python
delete() -> None
```

Delete this instruction.

**Example:**

```python
>>> instruction = api.node_instructions.get('instruction-id')
>>> instruction.delete()
```

```python
class air_sdk.endpoints.node_instructions.NodeInstructionEndpointAPI
```

**Bases**: `air_sdk.air_model.BaseEndpointAPI[air_sdk.endpoints.node_instructions.NodeInstruction]`

API client for node instructions endpoints.

```python
API_PATH: str
```

```python
model: type[NodeInstruction]
```

```python
create(
    *,
    node: str | PrimaryKey,
    executor: Literal[shell, init, file],
    data: ShellData | FileData | InitData,
    name: str | None = ...,
    run_again_on_rebuild: bool | None = ...
) -> NodeInstruction
```

Create a new node instruction.

**Parameters:**

* `node` – Node object or ID to execute the instruction on
* `name` – Name for the instruction
* `executor` – Type of executor ('shell', 'init', 'file')
* `data` – Instruction data/payload (executor-specific): ShellData - For 'shell' executor Contains: 'commands' (list of shell commands) FileData - For 'file' executor Contains: 'files' (list of dicts with 'path' and 'content') Optional: 'post\_commands' (shell commands to run after creating files) InitData - For 'init' executor Contains: 'hostname' (hostname to set for the node)
* `run_again_on_rebuild` – Optional whether to run instruction again on rebuild

**Returns:**

The created NodeInstruction instance

**Example:**

```python
>>> # Create shell instruction
>>> instruction = api.node_instructions.create(
...     name='Setup Script',
...     node='node-id',
...     executor='shell',
...     data=ShellData(commands=['#!/bin/bash\necho "Hello"']),
...     run_again_on_rebuild=True,
... )

>>> # Create file instruction
>>> instruction = api.node_instructions.create(
...     name='Install Package',
...     node='node-id',
...     executor='file',
...     data=FileData(
...         files=[{'path': 'package.txt', 'content': 'package=1.0.0'}],
...         post_commands=['#!/bin/bash\necho "Hello"'],
...     ),
...     run_again_on_rebuild=True,
... )

>>> # Create init instruction
>>> instruction = api.node_instructions.create(
...     name='Initialize Environment',
...     node='node-id',
...     executor='init',
...     data=InitData(hostname='my-node'),
...     run_again_on_rebuild=True,
... )
```

```python
list(
    *,
    created_by_client: bool = ...,
    executor: Literal[shell, init, file] = ...,
    name: str = ...,
    node: str = ...,
    run_again_on_rebuild: bool = ...,
    simulation: str = ...,
    state: str = ...,
    search: str = ...,
    ordering: str = ...,
    limit: int = ...,
    offset: int = ...
) -> Iterator[NodeInstruction]
```

List all node instructions.

**Parameters:**

* `created_by_client` – Filter by created by client
* `executor` – Filter by executor ('shell', 'init', 'file')
* `name` – Filter by name
* `node` – Filter by node
* `run_again_on_rebuild` – Filter by run\_again\_on\_rebuild
* `simulation` – Filter by simulation
* `state` – Filter by state
* `search` – Search by name
* `ordering` – Order by field
* `limit` – Limit the number of results
* `offset` – Offset the results

**Returns:**

Iterator of NodeInstruction instances

**Example:**

```python
>>> # List all instructions for a node
>>> for instruction in api.node_instructions.list(node='node-id'):
...     print(instruction.name)

>>> # List with multiple filters
>>> for instruction in api.node_instructions.list(
...     simulation='sim-id',
...     executor='shell',
...     state='complete',
...     ordering='-created',
... ):
...     print(instruction.name, instruction.state)
```

```python
get(pk: PrimaryKey) -> NodeInstruction
```

Get a specific node instruction by ID.

**Parameters:**

* `pk` – The node instruction ID (string or UUID)

**Returns:**

The NodeInstruction instance

**Example:**

```python
>>> instruction = api.node_instructions.get('instruction-id')
>>> print(instruction.name)
```

```python
patch(
    *,
    pk: PrimaryKey,
    name: str | None | dataclasses._MISSING_TYPE = ...,
    run_again_on_rebuild: bool | None | dataclasses._MISSING_TYPE = ...
) -> NodeInstruction
```

Partially update a node instruction.

**Parameters:**

* `pk` – The node instruction ID
* `name` – New name for the instruction
* `run_again_on_rebuild` – Whether to run again on rebuild

**Returns:**

The updated NodeInstruction instance

**Example:**

```python
>>> instruction = api.node_instructions.patch(
...     'instruction-id',
...     name='Updated Name',
...     run_again_on_rebuild=True
... )
```

```python
delete(pk: PrimaryKey) -> None
```

Delete a node instruction.

**Parameters:**

* `pk` – The node instruction ID

**Example:**

```python
>>> api.node_instructions.delete('instruction-id')
```