# AGENTS.md - acomo CLI Agent Guide

acomo CLI は acomo ワークフロー管理プラットフォームの公式 CLI です。
全ての acomo API をコマンドラインから呼び出せます。

## 認証

アクセストークンはブラウザで acomo にログインした後に入手し、CLI で保持します。

```bash
# 環境変数で認証（推奨・非インタラクティブ）
export ACOMO_ACCESS_TOKEN="your-token"
export ACOMO_TENANT_ID="your-tenant-id"

# または login で保存
acomo login --tenant-id <tenantId> --access-token <accessToken>
```

| 環境変数             | 説明                                            | 必須 |
| -------------------- | ----------------------------------------------- | ---- |
| `ACOMO_ACCESS_TOKEN` | アクセストークン                                | Yes  |
| `ACOMO_TENANT_ID`    | テナント ID                                     | Yes  |
| `ACOMO_BASE_URL`     | API Base URL（デフォルト: `https://acomo.app`） | No   |

## 出力形式

- **TTY（ターミナル直接）**: デフォルトは `text`
- **パイプ/リダイレクト**: デフォルトは `json`（自動検出）
- **明示指定**: `--format json` または `--format text`

AI エージェントは通常パイプ経由で呼び出すため、自動的に JSON が返されます。

## コマンドの使い方

```bash
acomo <operationId> [JSON引数]
```

### パラメータの渡し方

```bash
# 位置引数として
acomo <operationId> '{"key": "value"}'

# stdin から
echo '{"key": "value"}' | acomo <operationId>

# ファイルから
acomo <operationId> < params.json
```

### パラメータの確認

各コマンドの必須/任意パラメータは `--help` で確認できます。

```bash
acomo <operationId> --help
```

### コマンド一覧

```bash
acomo --help
```

## 終了コード

| Code | 意味                                                |
| ---- | --------------------------------------------------- |
| 0    | 成功                                                |
| 1    | 一般エラー（サーバーエラーなど）                    |
| 2    | 認証エラー（401/403）                               |
| 3    | バリデーションエラー（パラメータ不足、不正な JSON） |
| 4    | リソース未検出（404）                               |

## エラー出力形式

JSON モード（パイプ時のデフォルト）では、エラーは stderr に JSON で出力されます。

```json
{
  "error": true,
  "code": "AUTH_REQUIRED | FORBIDDEN | NOT_FOUND | API_ERROR | VALIDATION_ERROR | INVALID_INPUT | UNKNOWN_ERROR",
  "status": 401,
  "message": "エラーメッセージ",
  "suggestion": "対処方法（該当する場合）"
}
```

## 主要なワークフロー

### モデル操作

```bash
# モデル一覧
acomo listWorkflowModels

# フィルタ付き取得
acomo listWorkflowModels '{"filter":"{\"name\":{\"contains\":\"申請\"}}","take":"10"}'

# 特定のモデルを取得
acomo getWorkflowModel '{"modelId":"model-id"}'

# モデルを作成
acomo createWorkflowModel '{"createModelDto":{"name":"モデル名","definition":{},"dataSchema":{},"policy":{}}}'
```

### プロセス操作

```bash
# プロセス一覧
acomo listWorkflowProcesses

# プロセスを開始
acomo startWorkflowProcess '{"modelId":"model-id"}'

# プロセスを承認
acomo approveWorkflowProcess '{"processId":"process-id"}'

# プロセスを却下
acomo rejectWorkflowProcess '{"processId":"process-id"}'
```

### ユーザー・テナント情報

```bash
# 現在のユーザー
acomo getCurrentUser

# 現在のテナント
acomo getCurrentTenant

# ユーザー一覧
acomo listUsers
```

## Tips

1. パラメータ情報は `--help` で確認: `acomo <command> --help`
2. エラーハンドリングは終了コードを使用
3. JSON 出力はパイプ経由で自動有効化
4. 全コマンド一覧は `acomo --help` で確認