iMothership CLI

Run project commands and queue agents from your terminal or CI pipeline.

Install

Requires Node.js 22 or later and a checkout of the iMothership repository. The CLI is currently distributed with the repository and has not been published to npm. From the repository root:

npm install --global ./cli
imothership --help

You can also run node cli/bin/imothership.js --help without installing. No build is needed.

Authenticate

Create an active project API key in project settings. The key selects your project and acts as its owning user. Set IMOTHERSHIP_API_KEY, or use IMOTHERSHIP_TOKEN for a bearer token. Set only one.

PowerShell:

$env:IMOTHERSHIP_API_KEY = 'your-project-api-key'
$env:IMOTHERSHIP_API_URL = 'https://api.imothership.com'

Bash / zsh:

export IMOTHERSHIP_API_KEY='your-project-api-key'
export IMOTHERSHIP_API_URL='https://api.imothership.com'

The API URL defaults to production. Override it with IMOTHERSHIP_API_URL or --api-url http://localhost:8000. Use an origin without an /api suffix. In CI, inject credentials through your runner's secrets. The CLI does not save them to disk.

Run a command

imothership command run customer/list --data '{"limit":10}'
imothership command run customer/list --method GET --query limit=10
imothership command run customer/create --data @customer.json
imothership command run customer/list --data @query.json > customers.json

Replace the example paths with configured commands in your project, or use a command ID. POST is the default. GET accepts repeatable --query key=value options. Input must be a JSON object. Use --data @file.json to avoid shell quoting issues.

Read JSON from stdin:

cat customer.json | imothership command run customer/create --data -
# PowerShell
Get-Content -Raw customer.json | imothership command run customer/create --data -

Payloads and responses depend on the configured command. Requests execute real operations, including writes.

Queue an agent

imothership agent run 0123456789abcdef01234567

Use an agent ID from your project. The HTTP 202 response includes message, queueJobId, status and trackAt. Success means the run was queued; the CLI does not wait for completion. Agent payloads are not yet supported.

Retrieve agent logs

imothership agentlog search --project "Customer Support" --from 2026-09-01 --to 2026-09-10 --keyword invoice
imothership agentlog search --project "Customer Support" --limit 50 --skip 50 > logs.json

Calls authenticated GET /api/v1/agentlogs. Only --project is required. Project names match exactly, ignoring case. Project keys and agent tokens are restricted to their own project; user tokens follow project membership or organization-admin access. Unknown or inaccessible projects return 404. Duplicate accessible project names return 409; use a project key to select one.

Dates filter the log start date. Date-only values cover whole UTC days; ISO timestamps with a timezone are inclusive. Keyword searches literal text, ignoring case, in agent name, reference, response and activity. Omitted dates and keyword do not restrict the results.

Returns { project, docs, total, limit, skip, hasMore } with activity and response text, newest first. Includes task, AI and API logs. Page size defaults to 50 (maximum 100). --skip is a record offset. The CLI fetches one page at a time; no matches returns an empty docs array.

Output and automation

Successful response bodies are written unchanged to stdout, including JSON, CSV and binary output. Errors go to stderr. Requests are never automatically retried and redirects are not followed.

Exit code	Meaning
0	HTTP success, documentation or help
1	HTTP failure, redirect, connection error or timeout
2	Invalid arguments, configuration or JSON input

Command-specific errors inside an HTTP success response must be checked in the output. The default timeout is 180 seconds. Change it with --timeout 300000. A timed-out request may still be processing on the server; check before retrying.

Help and documentation

imothership command run --help
imothership agent run --help
imothership agentlog search --help
imothership docs
imothership docs --cli
imothership docs --openapi
imothership --version

The docs command prints a URL for your configured API host. It does not require authentication or launch a browser.