Concourse Shell#

The Concourse Shell (CaSH) is a built-in interactive interface for working with Concourse. CaSH supports two input modes — CCL commands and Groovy scripting — and includes features like tab completion, syntax highlighting, prepare mode, and persistent history.

Starting CaSH#

Warning

Make sure that Concourse is running before starting CaSH.

1	`concourse shell`

Connection Parameters#

Specify connection options to connect to a different server, port, or environment:

1 2	`concourse shell -h server.example.com -p 1717 \ -e production -u admin`

Option	Description	Default
`-h, --host`	Server hostname	`localhost`
`-p, --port`	Server port	`1717`
`-e, --environment`	Environment name	(default)
`-u, --username`	Username	`admin`
`--password`	Password (prompts if omitted)
`--prefs, --config`	Path to client config file

Non-Interactive Mode#

Run a single command and exit:

1	`concourse shell --run "select from 1"`

Dual-Mode Input#

CaSH accepts input in two modes. It tries the CCL command parser first, and falls back to Groovy if that fails.

CCL Commands#

Use natural, SQL-like syntax for common operations:

[default/cash]$ select "name", "age" from 1
[default/cash]$ find "age > 30"
[default/cash]$ add "name", "Jeff", 1
[default/cash]$ get "name" from 1 at "yesterday"

Groovy Mode#

For complex logic or operations not covered by CCL syntax, use the full Groovy scripting language. The concourse variable provides access to the complete Concourse API:

[default/cash]$ concourse.select(1)
[default/cash]$ concourse.find("age > 30")
[default/cash]$ concourse.get("name", 1,
    Timestamp.fromString("yesterday"))

Combined Error Reporting#

If input fails both modes, CaSH reports errors from both parsers to help you diagnose the issue.

Tab Completion#

CaSH provides context-aware tab completion. Press Tab to cycle through completions for:

Command verbs: select, find, add, get, etc.
Key names: Loaded from the server asynchronously
Operators: =, >, <, contains, etc.
Colon commands: :help, :prepare, etc.
Method names: Concourse API methods and their signatures

Completions are grouped by category and include signature hints to guide parameter entry.

Refreshing Completion Data#

Completion metadata is loaded from the server at startup. To reload it after schema changes:

1	`[default/cash]$ :refresh`

Syntax Highlighting#

CaSH highlights input in real time:

Command verbs in green
Colon commands in cyan
Groovy keywords in blue
Strings in yellow
Numbers in magenta
Comments in gray

Colon Commands#

CaSH provides built-in commands prefixed with : that control shell behavior.

Command	Description
`:help [command]`	Display help, optionally for a specific command
`:prepare`	Enter prepare mode
`:submit`	Submit all prepared commands
`:discard`	Discard prepared commands
`:stage`	Begin a transaction
`:commit`	Commit the active transaction
`:abort`	Abort the active transaction
`:reconnect`	Re-establish connection to the server
`:refresh`	Reload completion metadata from the server
`:history`	Display command history
`:load <path>`	Load and execute a script file
`:show records`	Display total record count
`:exit`	Exit CaSH

Prepare Mode#

Prepare mode lets you queue multiple commands and submit them as a batch. This is useful for building up a sequence of operations (including transactions) before executing them.

Enter Prepare Mode#

1	`[default/cash]$ :prepare`

The prompt changes to indicate prepare mode and shows the number of queued commands:

1	`[default/cash:prepare(0)]$`

Queue Commands#

Type commands as usual. Instead of executing immediately, they are queued:

[default/cash:prepare(0)]$ stage
[default/cash:prepare(1)]$ add "name", "Jeff", 1
[default/cash:prepare(2)]$ add "age", 30, 1
[default/cash:prepare(3)]$ commit

Submit or Discard#

Submit all queued commands:

1	`[default/cash:prepare(4)]$ :submit`

Or discard them:

1	`[default/cash:prepare(4)]$ :discard`

Transaction Validation#

CaSH validates transaction semantics as you queue commands. It warns you about issues like:

commit without a preceding stage
Nested stage calls
Unmatched abort

Run Commands File#

CaSH automatically loads and executes a .cashrc file from your home directory at startup. This seeds each session with common configuration, custom functions, and variables.

Custom Run Commands File#

1	`concourse shell --run-commands /path/to/my-cashrc`

Disable Run Commands#

1	`concourse shell --no-run-commands`

Custom Functions#

Define reusable functions in .cashrc using Groovy syntax:

def showKeys() {
  allkeys = describe(inventory()).values()
  result = []
  allkeys.each { keys ->
    keys.each { key ->
      result << key
    }
  }
  result.toSet()
}

Then invoke them in any session:

1 2	`[default/cash]$ showKeys() Returned '[manager, name, follows, age, friends]'`

Custom Variables#

Define variables that are available throughout the session:

1 2	`// .cashrc defaultRecords = [1, 2, 3, 4, 5]`

Built-in Functions#

CaSH provides several built-in utility functions:

time()#

Return the current timestamp or parse a natural language time description:

1
2
3

[default/cash]$ time()
[default/cash]$ time("yesterday")
[default/cash]$ time("3 days ago")

show()#

Display information about records:

1	`[default/cash]$ show records`

History#

CaSH maintains a persistent command history in ~/.cash_history. History survives across sessions.

View History#

1	`[default/cash]$ :history`

Navigate History#

Use the up and down arrow keys to scroll through previous commands.

Automatic Paging#

When output exceeds the terminal height, CaSH automatically pipes it through a pager (less) for comfortable reading. The pager exits when you press q, and the output remains visible in the terminal scrollback.

Reconnecting#

If the connection to the server is lost, use :reconnect to re-establish it using the same credentials:

1	`[default/cash]$ :reconnect`

CaSH also detects connection loss automatically and prompts you to reconnect.

Multi-Line Input#

CaSH supports multi-line input. Lines ending with an open parenthesis, bracket, brace, or escaped newline continue to the next line:

[default/cash]$ concourse.find(
>     Criteria.where()
>         .key("age")
>         .operator(Operator.GREATER_THAN)
>         .value(30)
>         .build())

The secondary prompt > indicates that CaSH is waiting for more input.

Dynamic Prompt#

The CaSH prompt displays the current environment and mode:

1
2
3

[default/cash]$              # Normal mode
[production/cash]$           # Connected to "production"
[default/cash:prepare(3)]$   # Prepare mode with 3 queued