---
title: Variable Reference
description: Complete reference for all variable substitutions available in Archon commands and workflows.
category: reference
area: workflows
audience: [user]
sidebar:
  order: 5
---

Archon substitutes variables in command files, inline prompts, and bash scripts before execution. There are three categories of variables: workflow variables (substituted by the workflow engine), positional arguments (substituted by the command handler), and node output references (DAG workflows only).

## Workflow Variables

These variables are substituted by the workflow executor in all node types (`command:`, `prompt:`, `bash:`, `loop:`).

| Variable | Resolves to | Notes |
|----------|-------------|-------|
| `$ARGUMENTS` | The user's input message that triggered the workflow | Primary way to pass user input to commands |
| `$USER_MESSAGE` | Same as `$ARGUMENTS` | Alias |
| `$WORKFLOW_ID` | Unique ID for the current workflow run | Useful for artifact naming and log correlation |
| `$ARTIFACTS_DIR` | Pre-created external artifacts directory (`~/.archon/workspaces/<owner>/<repo>/artifacts/runs/<id>/`) | Always exists before node execution; stored outside the repo to avoid polluting the working tree |
| `$BASE_BRANCH` | Base branch for git operations | Auto-detected from the repository's default branch, or set via `worktree.baseBranch` in `.archon/config.yaml`. Throws an error if referenced in a prompt but cannot be resolved |
| `$DOCS_DIR` | Documentation directory path | Configured via `docs.path` in `.archon/config.yaml`. Defaults to `docs/` when not set. Never throws |
| `$CONTEXT` | GitHub issue or PR context, if available | Populated when the workflow is triggered from a GitHub issue/PR. Replaced with empty string when unavailable |
| `$EXTERNAL_CONTEXT` | Same as `$CONTEXT` | Alias |
| `$ISSUE_CONTEXT` | Same as `$CONTEXT` | Alias |
| `$LOOP_USER_INPUT` | User feedback from an interactive loop approval gate | Only populated on the first iteration of a resumed interactive loop. Empty string on all other iterations |
| `$REJECTION_REASON` | Reviewer feedback from an approval node rejection | Only available in `on_reject` prompts. Empty string elsewhere |

### Context Variable Behavior

The three context aliases (`$CONTEXT`, `$EXTERNAL_CONTEXT`, `$ISSUE_CONTEXT`) all resolve to the same value. When no issue context is available, they are replaced with an empty string to avoid sending the literal `$CONTEXT` text to the AI.

If issue context is present but no context variable appears in the prompt, the context is **appended** to the end of the prompt automatically. This prevents duplicate context when a command explicitly uses `$CONTEXT`.

### `$BASE_BRANCH` Fail-Fast

Unlike other variables, `$BASE_BRANCH` will cause the workflow to **fail immediately** if:
- The variable is referenced in a prompt, AND
- Auto-detection from git fails, AND
- `worktree.baseBranch` is not set in `.archon/config.yaml`

If the variable is not referenced, no error occurs even if the base branch cannot be determined.

## Positional Arguments

These variables are substituted by the command handler when commands are invoked directly (outside workflows). They are processed before workflow variables.

| Variable | Resolves to | Notes |
|----------|-------------|-------|
| `$1` | First positional argument | Split by whitespace from the user's input |
| `$2` | Second positional argument | |
| `$3` ... `$9` | Third through ninth positional arguments | |
| `$ARGUMENTS` | All arguments as a single string | Same variable, available in both contexts |
| `\$` | Literal `$` character | Escape a dollar sign to prevent substitution |

## Node Output References

In DAG workflows, nodes can reference the output of any completed upstream node. These are substituted after workflow variables.

| Pattern | Resolves to | Notes |
|---------|-------------|-------|
| `$nodeId.output` | Full output string of the referenced node | The node must be a declared dependency (in `depends_on`) |
| `$nodeId.output.field` | A specific JSON field from the node's output | Requires the upstream node to use `output_format` for structured JSON |

### Example

```yaml
nodes:
  - id: classify
    command: classify-issue
    output_format:
      type: object
      properties:
        type: { type: string, enum: [BUG, FEATURE] }
      required: [type]

  - id: fix
    prompt: |
      The issue was classified as: $classify.output.type
      Full classification: $classify.output
      User's original request: $USER_MESSAGE
    depends_on: [classify]
```

## Substitution Order

Variables are substituted in a defined order:

1. **Workflow variables** -- `$WORKFLOW_ID`, `$USER_MESSAGE`, `$ARGUMENTS`, `$ARTIFACTS_DIR`, `$BASE_BRANCH`, `$DOCS_DIR`, `$LOOP_USER_INPUT`, `$REJECTION_REASON`
2. **Context variables** -- `$CONTEXT`, `$EXTERNAL_CONTEXT`, `$ISSUE_CONTEXT`
3. **Node output references** -- `$nodeId.output`, `$nodeId.output.field`

Positional arguments (`$1` through `$9`) are substituted separately by the command handler and are only available when commands are invoked directly, not through workflow nodes.

## Variable Availability by Context

| Variable | Workflow nodes | Direct command invocation | `when:` conditions |
|----------|---------------|--------------------------|-------------------|
| `$ARGUMENTS` / `$USER_MESSAGE` | Yes | Yes (as `$ARGUMENTS`) | No |
| `$1` ... `$9` | No | Yes | No |
| `$WORKFLOW_ID` | Yes | No | No |
| `$ARTIFACTS_DIR` | Yes | No | No |
| `$BASE_BRANCH` | Yes | No | No |
| `$DOCS_DIR` | Yes | No | No |
| `$CONTEXT` / aliases | Yes | No | No |
| `$LOOP_USER_INPUT` | Yes (loop nodes) | No | No |
| `$REJECTION_REASON` | Yes (`on_reject` only) | No | No |
| `$nodeId.output` | Yes (DAG nodes) | No | Yes |
