CLI Reference

The Maritime CLI lets you deploy and manage agents from your terminal. First time here? The quickstart walks the happy path; this page is the full reference.

Installation

npm install -g maritime-cli

Requires Node.js 20.12 or later.

Authentication

maritime login

Authenticate with your Maritime account. Opens your browser for login by default, or pass credentials directly for non-interactive use. Sign in with Google or GitHub? You have no password, so use the browser flow, or paste a token from maritime.sh/cli/auth (ideal for headless servers, SSH sessions, and CI).

maritime login

# SSO / headless / CI: paste a token from https://maritime.ac/cli/auth
maritime login --token <token>
# ...or export it (equivalent, no stored config):
export MARITIME_TOKEN=<token>

# Non-interactive login (email/password accounts):
maritime login -e user@example.com -p yourpassword

maritime signup

Create a new Maritime account. Prompts interactively for any fields not provided.

maritime signup -e user@example.com -p yourpassword -n "Jane Doe"

# Or just run and follow the prompts:
maritime signup

maritime logout

Log out and clear stored credentials.

maritime logout

maritime whoami

Show the current authentication: the token source (MARITIME_TOKEN vs stored login), user, and expiry. Add --json for a machine-readable { authenticated, method, source, expiresAt } (exit code 2 when unauthenticated).

maritime whoami

maritime keys

Mint a long-lived API key (mk_…) for non-interactive use. Set it as MARITIME_TOKEN so an AI agent, script, or CI never runs an interactive login. Keys don't expire; revoke anytime.

# Mint a key (shown once, store it securely):
maritime keys create --name my-agent --json

# Default is FULL access (provision,deploy,secrets,manage). Narrow it for
# anything you hand to an agent or CI ("manage" can mint further keys):
maritime keys create --name ci-deploy --scopes deploy

# Use it everywhere:
export MARITIME_TOKEN=mk_xxxxxxxxxxxx

# List / revoke:
maritime keys list
maritime keys revoke <id>

Projects: a directory is an agent

Like vercel or railway, you can link a directory to an agent. After that, the agent argument is optional on every command; the CLI resolves the linked agent by walking up from the current folder. Two files: maritime.json (committed config: name, template, persona, env keys) and .maritime/ (the machine-local link, git-ignored).

maritime init support-bot     # scaffold maritime.json + AGENTS.md, create & link
maritime chat "what's open?"  # talks to support-bot, no name needed
maritime logs                 # support-bot's logs
maritime deploy               # reconcile the agent to maritime.json, then redeploy

maritime init

Scaffold maritime.json + AGENTS.md, create the agent, and link this directory to it. Defaults the template to openclaw and the name to the folder.

maritime init                 # name from the folder
maritime init support-bot     # explicit name
maritime init bot --no-create # just write the config files

maritime link

Link this directory to an existing agent (interactive picker if no name is given). Re-run to change it.

maritime link support-bot
maritime link                 # pick from your agents

Agent Management

maritime create

Create a new agent. Just give it a name: the platform picks an applicable size for the framework, and the agent auto-sleeps when idle and wakes on the next message. No sizing required.

maritime create my-agent

# From a template (see maritime templates):
maritime create researcher --template openclaw

# With initial environment variables:
maritime create my-agent -e OPENAI_API_KEY=sk-... -e MY_VAR=hello

# From a GitHub repo (must contain a Dockerfile), served on a public URL:
maritime create my-app --repo https://github.com/you/app --public --port 3000

Serving a repo on a public URL is covered in Public web agents.

Advanced: per-agent resource overrides. All optional; omit them and the agent gets the platform defaults. Useful for hand-tuning a single agent (e.g. a reseller dialing resources per client). Hidden from --help, but fully supported.

maritime create acme-bot --ram 2048 --cpu 1.5 --idle 600 --disk 20
maritime create always-up --always-on

maritime list

List all your agents with their status, framework, and creation date. Alias: maritime ls

maritime list

# Output:
# NAME            STATUS     FRAMEWORK    CREATED
# support-bot     active     openclaw     2026-04-12
# data-pipeline   sleeping   zeroclaw     2026-03-28
# code-reviewer   sleeping   openclaw     2026-05-01

maritime deploy

Deploy an agent. Accepts an agent name or ID prefix.

maritime deploy my-agent

# Deploy from a GitHub repo:
maritime deploy my-agent --source github --repo https://github.com/user/repo

# Deploy a specific Docker image:
maritime deploy my-agent --source docker --image myimage:latest

maritime start / stop / restart

Manual lifecycle control, rarely needed. Serverless agents auto-sleep when idle and auto-wake on the next message or trigger; reach for these for ops or debugging. (Hidden from maritime --help, still fully supported.)

maritime start my-agent
maritime stop my-agent
maritime restart my-agent

maritime delete

Delete an agent. Prompts for confirmation unless -y is passed.

maritime delete my-agent

# Skip confirmation:
maritime delete my-agent -y

Talking to agents

maritime chat

Send a message to a running agent and print its reply. Reads the message from arguments or stdin (handy for long prompts). Sleeping serverless agents auto-wake. Alias: maritime send.

maritime chat my-agent "summarize today's incidents"

# Long prompt via stdin:
cat prompt.txt | maritime chat my-agent

# Multi-turn with a conversation id:
maritime chat my-agent "and the one before?" --conversation-id abc123

# Machine-readable (returns { response }):
maritime chat my-agent "hi" --json

Your end users

An end user is one of your users, keyed by the id you already hold for them. Their agents, spend caps, delegated tokens and costs hang off that record; the Users page shows the same list and the SDK guide covers the model. The CLI is for support work and scripts.

maritime users

# Create or update one (safe to run on every sign-in):
maritime users upsert user_42 --name "Ada" --tag pro --meta plan=pro

# Their agent, exactly once (a repeat call returns the same agent):
maritime users create user_42 --template openclaw
maritime users agents user_42

# Caps and sizing, applied to every agent they own:
maritime users policy set user_42 --llm-cap-cents 500 --wakes-per-hour 60 --idle-seconds 600
maritime users policy get user_42
maritime users policy clear user_42

# A short-lived eu_ token for their own browser or app (shown once):
maritime users token user_42 --scopes chat,files --ttl 900 --json
maritime users revoke-tokens user_42

# Find, inspect, suspend, resume, delete:
maritime users list --tag pro --status active
maritime users get user_42
maritime users suspend user_42
maritime users resume user_42
maritime users delete user_42 --yes      # agents and tokens go with it

Policy flags: --llm-cap-cents (AI spend per month), --compute-minutes, --wakes-per-hour, --idle-seconds, --ram (MB), --cpu, --disk (GB). set replaces the whole policy. Token scopes: chat, files, console, logs, app; the TTL is 30 to 3600 seconds.

Observability

maritime logs

View logs from an agent.

maritime logs my-agent

# Show last 100 lines:
maritime logs my-agent -n 100

# Filter by level:
maritime logs my-agent --level error

# Stream logs live:
maritime logs my-agent -f

maritime env

Manage environment variables for an agent.

# List variables:
maritime env list my-agent

# Set one or more (marked secret + encrypted by default):
maritime env set my-agent OPENAI_API_KEY=sk-... ANOTHER=value

# Bulk import from a .env file (or stdin), then hot-reload:
maritime env import my-agent ./prod.env --reload

# Set a non-secret variable:
maritime env set my-agent LOG_LEVEL=debug --no-secret

# Remove a variable:
maritime env remove my-agent LOG_LEVEL

# Apply pending changes to a running agent without a full restart:
maritime env reload my-agent

# Pull the agent's env into a local .env file (secret values are masked):
maritime env pull my-agent .env

Env changes apply on the next container boot unless you pass --reload (or run maritime env reload). Secrets behavior is covered in Env vars & sizing.

maritime status

Show detailed status for a single agent: health, last activity, container ID, host, and deployment state.

maritime status my-agent

maritime usage

What your agents cost over a range: per agent, per end user (--by-user, the rebilling view) or per day (--daily). Under a seat plan the hosting number is your plan price allocated over your agents day by day; AI is the real spend from your credits. The summary at the top of the Users page draws the same numbers by day.

maritime usage                                  # last 30 days, per agent
maritime usage --by-user --json                 # cost per end user
maritime usage --daily --days 7
maritime usage --from 2026-09-01 --to 2026-10-01 --by-user

maritime info

Print full metadata for an agent (env keys, framework, image, exposed ports, server placement).

maritime info my-agent

maritime history

Show deployment history for an agent: every build/deploy attempt with its outcome.

maritime history my-agent

# Show last 30 deployments:
maritime history my-agent -n 30

maritime triggers

Manage the cron/webhook/telegram/discord triggers wired to an agent. Subcommands, not a bare argument:

maritime triggers list my-agent

maritime triggers create my-agent --type cron --cron "0 9 * * *"
maritime triggers create my-agent --type webhook

maritime triggers delete my-agent <trigger-id>

A cron trigger wakes the agent on schedule; give it a message to deliver by setting config.prompt via the API, or let the agent publish its own schedule (see Triggers & schedules).

Lifecycle

maritime sleep

Put an active agent to sleep. Sleeping agents keep their full state, still count against your plan, and auto-wake on triggers. (Wake timings and the full model are in How Maritime works.)

maritime sleep my-agent

maritime open

Open the agent's dashboard page in your default browser.

maritime open my-agent

Discovery

maritime templates

List available agent templates. This command does not require authentication.

maritime templates

maritime guide

Print the machine-readable usage guide for driving the CLI from code or an AI agent. --json emits a one-shot manifest of every command, flag, and the contract, introspected live so it can't drift.

maritime guide          # human-readable contract
maritime guide --json   # full command/flag manifest

maritime exec

Runs an attached, non-interactive command. The CLI has no detached, timeout, retrieval, or cancellation flags. Its execution timeout defaults to 60 seconds. Use the REST exec API for a custom timeout or detached execution.

maritime exec my-agent ls /data --json

On agents with detached support, JSON output includes executionId, status, exitCode, stdout, and stderr. Without --json, command output goes to the corresponding stdout and stderr streams. On agents with detached support, disconnecting does not cancel the command. Older agents still support this command, but return combined output in stdout and omit executionId and status. Use a new agent for detached execution through the REST API.

Scripting & AI agents

Handing the CLI to Claude, Cursor, or another assistant? There's a ready-made prompt and a walkthrough on Drive Maritime from an AI agent; the tables below are the underlying contract.

The CLI is built to be driven non-interactively. Authenticate with the MARITIME_TOKEN env var (an mk_… key from maritime keys create), pass --json on every command, and branch on the exit code.

With --json: success prints one JSON value to stdout (stderr empty); failure prints one JSON object { ok: false, error: { code, message } } to stderr (stdout empty).

export MARITIME_TOKEN=mk_xxxxxxxxxxxx

# results on stdout, errors on stderr, branch on exit code:
maritime list --json | jq '.[] | select(.status=="error") | .name'

reply=$(maritime chat my-agent "status?" --json | jq -r '.response')