iMothership CLI

Call the same endpoints as the API reference using the exact API paths, methods and field names. The CLI rejects undocumented routes and methods and returns API response bodies unchanged.

Install

Requires Node.js 22 or later and a repository checkout. The CLI has not been published to npm. From the repository root:

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

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

Authenticate

Use the same active project API key as Authorize in the API reference.

API keys use a project service identity by default and do not depend on the creator's login. For task authoring or operations requiring a user identity, an organization administrator must select a Run as user for the key in Project API Keys. That user must remain a member of the project and organization. Webhook secrets cannot authenticate API requests.

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 default host is https://api.imothership.com. Override it with IMOTHERSHIP_API_URL or --api-url http://localhost:8000, without an /api suffix. Credentials are not saved. Public endpoints send no API key. Bearer tokens are not supported; unset IMOTHERSHIP_TOKEN for authenticated requests.

Make a request

imothership request GET /api/v1/logs --query from=2026-10-08 --query to=2026-10-08 --query task=Email/TEST --query keyword=invoice --query limit=50 --query skip=0
imothership request GET /api/v1/tasks --query limit=50 --query skip=0
imothership request GET /api/v1/tasks/{{task.name}}
imothership request POST /api/v1/tasks/createOrUpdateTask --data @task.json
imothership request POST /api/v1/tasks/validate --data @task.json
imothership request POST /api/v1/task/{{task.name}}
imothership request GET /api/v1/models --query type=1
imothership request POST /api/v1/api/customer/list --data @query.json
imothership request GET /api/v1/skill/customer/guide

Use API field names unchanged in repeatable --query key=value options and JSON bodies. Replace {{task.name}} with a URL-encoded task name or a task ID. Both reading and running a task accept either. Names match exactly, ignoring case, within your project. Duplicate names return 409; use the task ID. URL-encode spaces and slashes in path parameters; the CLI encodes query values for you. Optional fields are omitted unless supplied. API defaults and validation apply; Swagger example values are not inserted.

JSON input can be inline, @file.json or stdin with --data -. Files avoid shell quoting issues. For example:

cat task.json | imothership request POST /api/v1/tasks/validate --data -
# PowerShell
Get-Content -Raw task.json | imothership request POST /api/v1/tasks/validate --data -

Authenticated Endpoints

Public Endpoints

Plural /api/v1/apis and /api/v1/skills routes read and author raw definitions without executing source or expanding tags. List definitions to obtain IDs. Updates require the id and latest revision returned by GET. Creates require request and content, plus work_id if the project has no Data work. The source work must belong exclusively to the project. Validation checks fields and references without executing JavaScript. A save with storage_synced: false has saved the definition but needs its download copy synchronized.

imothership request GET /api/v1/apis
imothership request GET /api/v1/apis/{{api.id}}
imothership request POST /api/v1/apis/validate --data @api-definition.json
imothership request POST /api/v1/apis/createOrUpdateApi --data @api-definition.json
imothership request GET /api/v1/skills/{{skill.id}}
imothership request POST /api/v1/skills/createOrUpdateSkill --data @skill-definition.json

See the API reference for field definitions, permissions and response schemas.

imothership request POST /api/v1/webhook/YOUR_WEBHOOK_ID --data @event.json
imothership request POST /api/v1/webhook/YOUR_WEBHOOK_ID --content-type text/plain --data @event.txt
imothership request GET /api/pack/public --query limit=100
imothership request POST /api/public-ai/message --data @message.json

Webhooks also accept the API's resume query field. Keep webhook IDs private.

Output and automation

HTTP response bodies are written byte-for-byte to stdout on success and stderr on failure, including JSON, text, CSV and binary content. No wrappers, truncation, redaction or extra newlines are added. Network and configuration failures use CLI diagnostics because there is no API response body.

imothership request GET /api/v1/logs > logs.json 2> error.json

Each invocation makes one API request. The CLI does not follow redirects, retry automatically, fetch extra pages or poll queued tasks. The default timeout is 180 seconds; change it with --timeout 300000. A timed-out request may still be processing; check before retrying.

The legacy command run, agent run, agentlog search and --project options have been removed. Use the exact documented API paths above.

Help and documentation

imothership request --help
imothership docs
imothership docs --cli
imothership docs --openapi
imothership --version

The docs command prints a URL for your configured host without authentication or opening a browser.