CLI Reference#

The Adama CLI is your main tool for developing, testing, deploying, and managing Adama applications. This page covers every command and its options. When adama --help doesn't tell you enough, come here.

Installation and Setup#

Downloading the CLI#

# Using wget
wget https://aws-us-east-2.adama-platform.com/adama.jar

# Using curl
curl -fSLO https://aws-us-east-2.adama-platform.com/adama.jar

Running Commands#

All commands are run using:

java -jar adama.jar <command> [options]

Creating an Alias#

Add to your shell configuration (.bashrc, .zshrc, etc.):

alias adama="java -jar /path/to/adama.jar"

Then:

adama <command> [options]

Global Options#

These work with any command:

Account Commands#

init#

Initialize a developer account and create local configuration. This is the first thing you run.

adama init

Interactive Process:

1. Accept terms and conditions
2. Enter email address
3. Receive and enter verification code
4. Optionally revoke previous sessions

Options:

Examples:

# Interactive initialization
adama init

# With email pre-specified
adama init --email developer@example.com

Space Commands#

Spaces are named containers for your Adama code. Each space can have multiple documents running the same code.

space create#

Create a new space.

adama space create --name <space-name>

Options:

Examples:

# Create a new space
adama space create --name my-game

# Create from template
adama space create --name my-app --template chat

space list#

List all spaces owned by your account.

adama space list

Output: JSON array of space information including names, creation dates, and deployment status.

space deploy#

Deploy Adama code to a space. This is how you ship.

adama space deploy --name <space-name> --file <path>

Options:

Examples:

# Deploy code to a space
adama space deploy --name my-game --file game.a

# Deploy with garbage collection
adama space deploy --name my-game --file game.a --gc

space delete#

Delete a space. This is permanent.

adama space delete --name <space-name>

Options:

Examples:

# Delete with confirmation prompt
adama space delete --name old-project

# Delete without prompt
adama space delete --name old-project --confirm

space get#

Get information about a space.

adama space get --name <space-name>

Output: JSON object with space details including current deployment, statistics, and configuration.

space set-rxhtml#

Upload RxHTML files to a space.

adama space set-rxhtml --name <space-name> --file <path>

Options:

space get-rxhtml#

Download RxHTML files from a space.

adama space get-rxhtml --name <space-name> --output <path>

Document Commands#

Documents are instances of a space's deployed code. Each document is an independent stateful VM.

document create#

Create a new document in a space.

adama document create --space <space> --key <key>

Options:

Examples:

# Create a document
adama document create --space my-game --key game-123

# Create with constructor argument
adama document create --space my-game --key game-123 --arg '{"maxPlayers": 4}'

document delete#

Delete a document.

adama document delete --space <space> --key <key>

Options:

document list#

List documents in a space.

adama document list --space <space>

Options:

document connect#

Connect to a document and stream updates. This is great for debugging -- you can watch deltas come in real time.

adama document connect --space <space> --key <key>

Options:

Streams JSON deltas to stdout as the document changes. Press Ctrl+C to disconnect.

document send#

Send a message to a document channel.

adama document send --space <space> --key <key> --channel <channel> --message <json>

Options:

Examples:

# Send a message
adama document send --space my-game --key game-123 \
  --channel join --message '{"playerName": "Alice"}'

Code Commands#

code validate#

Validate Adama code without deploying. Catches errors before you ship -- always a good idea.

adama code validate --file <path>

Options:

Examples:

# Validate a file
adama code validate --file game.a

# Validate with includes
adama code validate --file game.a --includes ./lib

code compile#

Compile Adama code and output results.

adama code compile --file <path>

Options:

code test#

Run tests defined in Adama code.

adama code test --file <path>

Options:

Examples:

# Run all tests
adama code test --file game.a

# Run specific tests
adama code test --file game.a --filter "Auth_*"

code lsp#

Start the Language Server Protocol server for IDE integration.

adama code lsp

Used by IDE extensions to provide syntax highlighting, error checking, and autocompletion.

code format#

Format Adama source code.

adama code format --file <path>

Options:

Examples:

# Preview formatted output
adama code format --file game.a

# Format in place
adama code format --file game.a --write

Kickstart Command#

kickstart#

Create a new project from a template with all the files you need to get going.

adama kickstart --template <template> --output <directory>

Options:

Available Templates:

Examples:

# Create a chat app
adama kickstart --template chat --output ./my-chat-app

# Create a game project
adama kickstart --template game --output ./my-game --name "Card Battle"

Development Server#

devbox#

Run a local development server with hot-reloading. This is where you'll spend most of your time during development.

adama devbox --space <space>

Options:

Features:

• Auto-reloads on file changes
• Serves RxHTML frontend
• Proxies to Adama backend
• Live error reporting

Examples:

# Start dev server
adama devbox --space my-app --file main.a --rxhtml ./frontend

# Custom port
adama devbox --space my-app --port 3000 --file main.a

Authority Commands#

Authorities manage authentication and identity.

authority create#

Create a new authority.

adama authority create --name <name>

authority list#

List all authorities.

adama authority list

authority sign#

Sign a token with an authority.

adama authority sign --name <name> --agent <agent>

Options:

Domain Commands#

domain map#

Map a custom domain to a space.

adama domain map --domain <domain> --space <space>

Options:

domain list#

List all domain mappings.

adama domain list

domain unmap#

Remove a domain mapping.

adama domain unmap --domain <domain>

Utility Commands#

help#

Show help for any command.

adama help
adama help <command>
adama <command> --help

Examples:

adama help space
adama space deploy --help

version#

Show CLI version information.

adama version

Configuration File#

The CLI stores configuration in ~/.adama by default. This JSON file contains:

{
  "identity": "your-identity-token",
  "email": "your@email.com",
  "default-space": "my-project"
}

Overriding Configuration#

Use the --config flag to use a different configuration file:

adama --config /path/to/config space list

Useful for managing multiple accounts, CI/CD environments, or team-shared configurations.

Exit Codes#

Environment Variables#

Common Workflows#

Development Workflow#

# 1. Create a space
adama space create --name my-project

# 2. Write and test code
adama code test --file main.a

# 3. Deploy code
adama space deploy --name my-project --file main.a

# 4. Create a document
adama document create --space my-project --key doc-1

# 5. Run dev server
adama devbox --space my-project --file main.a --rxhtml ./frontend

Deployment Workflow#

# Validate code
adama code validate --file main.a

# Run tests
adama code test --file main.a

# Deploy to production
adama space deploy --name production --file main.a

Debugging Workflow#

# Connect to document and watch state
adama document connect --space my-app --key doc-123

# Send test messages
adama document send --space my-app --key doc-123 \
  --channel test --message '{"value": 42}'