Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update README #89

Merged
merged 4 commits into from
Nov 17, 2023
Merged

Update README #89

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c44bc18
Update README
makoto-soracom Nov 15, 2023
72a1dac
Reflect ogu's comment
makoto-soracom Nov 17, 2023
6b5649e
improve english sentences
bearmini Nov 17, 2023
259a79f
fix typo
bearmini Nov 17, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 33 additions & 35 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

# soracom-cli

A command line tool `soracom` to invoke SORACOM API.
Provides `soracom` command, a command line tool for calling SORACOM APIs.

# Feature

Expand All @@ -14,29 +14,32 @@ The `soracom` command:

- just works by copying the cross-compiled binary file into the target environment. There is no need to build an environment or solve dependencies.

- constructs a request based on the specified argument and calls the SORACOM API. Response (JSON) from the API is output directly to standard output.
- constructs a request based on the specified arguments and calls the SORACOM API. Response (JSON) from the API is output directly to standard output.
- This makes it easier to process the output of the soracom command and pass it to another command

- supports bash completion. Please write the following line in .bashrc etc
```
eval "$(soracom completion bash)"
```

if you are a macOS user, you probably need to either:
1. use `bash` version >= 4.0, or
2. use `brew install bash-completion` instead of using Xcode version of bash-completion and then add the following to either your `.bash_profile` or `.profile`:
- If you get an error like this:

```
if [ -f "$(brew --prefix)/etc/bash_completion" ]; then
. "$(brew --prefix)/etc/bash_completion"
fi
```
otherwise you might be getting the error like the following:
```
-bash: __ltrim_colon_completions: command not found
```
```
-bash: __ltrim_colon_completions: command not found
```

This error may appear if you are using macOS. You might need to satisfy one of the following conditions:

- supports zsh completion. The generated completion script by running the following command should be put somewhere in your $fpath named `_soracom`
- use `bash` version >= 4.0, or
- use `brew install bash-completion` instead of using Xcode version of bash-completion and then add the following to either your `.bash_profile` or `.profile`:

```
if [ -f "$(brew --prefix)/etc/bash_completion" ]; then
. "$(brew --prefix)/etc/bash_completion"
fi
```

- supports zsh completion. The generated completion script by running the following command should be put somewhere in your `$fpath` named `_soracom`
```
soracom completion zsh
```
Expand Down Expand Up @@ -136,7 +139,7 @@ Thereafter, when executing the soracom command, an API call is made using the au

### Use multiple profiles

If you have multiple SORACOM accounts or want to use multiple SAM users differently, specify the --profile option to configure and set the profile name.
If you have multiple SORACOM accounts or want to use multiple SAM users differently, specify the `--profile` option to configure and set the profile name.

```
soracom configure --profile user1
Expand All @@ -149,7 +152,7 @@ soracom configure --profile user2
```

This will create profiles named user1 and user2.
To use the profile, specify the --profile option in addition to the normal command.
To use the profile, specify the `--profile` option in addition to the normal command.

```
soracom subscribers list --profile user1
Expand Down Expand Up @@ -204,18 +207,18 @@ These keys and tokens are then sent along with the API requests.

There are several options available to authenticate or to specify the API key and token, which are used as follows:

1. Use the previously authenticated and obtained API key and token directly by specifying them with the --api-key and --api-token options to make API calls.
1. Use the previously authenticated and obtained API key and token directly by specifying them with the `--api-key` and `--api-token` options to make API calls.

2. Authenticate by specifying the authentication key ID and authentication key with the --auth-key-id and --auth-key options, then obtain the API key and token, and use them to make API calls.
2. Authenticate by specifying the authentication key ID and authentication key with the `--auth-key-id` and `--auth-key options`, then obtain the API key and token, and use them to make API calls.

3. Generate a profile (which contains the information for authentication) by executing an external command specified by the --profile-command option, then use that profile to authenticate, obtain the API key and token, and make the API calls.
3. Generate a profile (which contains the information for authentication) by executing an external command specified by the `--profile-command` option, then use that profile to authenticate, obtain the API key and token, and make the API calls.

4. Authenticate using a pre-configured profile specified with the --profile option, then obtain the API key and token, and use them to make the API calls.
4. Authenticate using a pre-configured profile specified with the `--profile` option, then obtain the API key and token, and use them to make the API calls.

These methods are ranked in priority from 1 to 4, with 1 being the highest priority and 4 the lowest.
For example, if a soracom-cli user specifies both the --profile-command and --profile options at the same time, the contents of the --profile-command option will take precedence.
For example, if a soracom-cli user specifies both the `--profile-command` and `--profile` options at the same time, the contents of the `--profile-command` option will take precedence.

Additionally, if options that need to be specified together, like --api-key and --api-token or --auth-key-id and --auth-key, are provided singly, it will result in an error.
Additionally, if options that need to be specified together, like `--api-key` and `--api-token` or `--auth-key-id` and `--auth-key`, are provided singly, it will result in an error.


### Priority of authentication methods specified in the profile
Expand Down Expand Up @@ -255,7 +258,7 @@ Or
HTTP_PROXY=http://10.0.1.2:8080 soracom subscribers list
```

### Use AWS Lambda Layers
### Use AWS Lambda Layers of soracom-cli

Have you ever thought about using soracom-cli on AWS Lambda? By including the soracom-cli binary in your Zip package or container image and deploying it, you can use soracom-cli in your Lambda functions.

Expand Down Expand Up @@ -331,17 +334,12 @@ export SORACOM_AUTHKEY_FOR_TEST=...
./test/test.sh $VERSION
```

### Troubleshooting Build Issues

# How to release
If you encounter an error like `go: could not create module cache: mkdir /go/pkg: permission denied` during the build process, please check the permissions of /go/pkg inside the Docker container. In the build.sh script, we mount the host's `${GOPATH:-$HOME/go}` to /go/pkg, so you should check the permissions of `$GOPATH` or `$HOME/go` on the host. In most cases, the following command should resolve the issue:

```
VERSION=1.2.3 # => specify a version number to be released
./scripts/build.sh $VERSION # => build a version to be released
./test/test.sh $VERSION # => test the version
# commit & push all changes to github
./scripts/release.sh $VERSION # => release the version to GitHub
# edit the release on github.com release page
./scripts/update-homebrew-formula.sh $VERSION $GITHUB_USERNAME $GITHUB_EMAIL
./scripts/build-lambda-layer.sh $VERSION
./scripts/release-lambda-layer.sh $VERSION $AWS_PROFILE # => this command releases the layer to all regions (except ap-east-1)


```bash
sudo chown -R $USER:$USER ${GOPATH:-$HOME/go}
```
61 changes: 36 additions & 25 deletions README_ja.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,20 +22,22 @@ soracom コマンドは以下のような特徴を備えています。
eval "$(soracom completion)"
```

macOS をお使いの場合、以下のいずれかの条件を満たす必要があるかもしれません：
1. `bash` のバージョン 4.0 以降を使用する
2. `brew install bash-completion` でインストールした bash-completion を使う（Xcode に付属の bash-completion では動作しない場合があります。）
そしてこの場合、`.bash_profile` または `.profile` ファイルに以下を追加します:
- 以下のようなエラーが起きたときは:

```
if [ -f "$(brew --prefix)/etc/bash_completion" ]; then
. "$(brew --prefix)/etc/bash_completion"
fi
-bash: __ltrim_colon_completions: command not found
```

以下のようなエラーが起きた場合は上記いずれかをお試し下さい。
```
-bash: __ltrim_colon_completions: command not found
```
このエラーは macOS をお使いの場合に表示されることがあります。以下のいずれかの条件を満たす必要があるかもしれません：
- `bash` のバージョン 4.0 以降を使用する
- `brew install bash-completion` でインストールした bash-completion を使う（Xcode に付属の bash-completion では動作しない場合があります。）

そしてこの場合、`.bash_profile` または `.profile` ファイルに以下を追加します:
```
if [ -f "$(brew --prefix)/etc/bash_completion" ]; then
. "$(brew --prefix)/etc/bash_completion"
fi
```

- zsh completion（引数補完）に対応しています。以下のようなコマンドを実行して生成されるスクリプトを `_soracom` という名前で `$fpath` のどこかに配置してください。
```
Expand All @@ -57,7 +59,7 @@ brew install bash-completion
以下に紹介するいずれかのコマンドを実行することで、最新版の `soracom` コマンドがダウンロードされてインストールされます。


もし `/usr/local/bin` にファイルを書き込む権限のあるユーザー（root など）でインストールする場合はいかのコマンドを実行してください。
もし `/usr/local/bin` にファイルを書き込む権限のあるユーザー（root など）でインストールする場合は以下のコマンドを実行してください。

```shell
curl -fsSL https://raw.githubusercontent.com/soracom/soracom-cli/master/install.sh | bash
Expand Down Expand Up @@ -141,7 +143,7 @@ SAM ユーザーに対し認証キーを発行する方法についてはソラ

### 複数のプロファイルを使い分ける

SORACOM アカウントを複数所有しているとか、複数の SAM ユーザーを使い分けたい場合は、configure に --profile オプションを指定し、プロファイル名を設定します。
SORACOM アカウントを複数所有しているとか、複数の SAM ユーザーを使い分けたい場合は、configure に `--profile` オプションを指定し、プロファイル名を設定します。

```
soracom configure --profile user1
Expand All @@ -154,7 +156,7 @@ soracom configure --profile user2
```

このようにすると user1 および user2 という名前のプロファイルが作成されます。
プロファイルを利用する場合は通常のコマンドの後ろに --profile オプションを指定します。
プロファイルを利用する場合は通常のコマンドの後ろに `--profile` オプションを指定します。

```
soracom subscribers list --profile user1
Expand Down Expand Up @@ -216,7 +218,7 @@ soracom-cli は SORACOM API を呼び出すために、通常は内部的に認
4. 事前に構成されたプロファイルを`--profile` オプションで指定し、そのプロファイルを用いて認証を行って API キーとトークンを取得し、それらを用いて API を呼び出す

これらは 1 から 4 の順に優先されます。すなわち、1 が最も優先され、4 の優先度が最も低くなります。
たとえば、もし `soracom-cli` のユーザーが `--profile-command` オプションと `--profile` オプションを同時に指定してしまった場合、`--profile-command` オプションの内容が優先されます。
たとえば、もし soracom-cli のユーザーが `--profile-command` オプションと `--profile` オプションを同時に指定してしまった場合、`--profile-command` オプションの内容が優先されます。

また、`--api-key` と `--api-token` や `--auth-key-id` と `--auth-key` のように、2 つ同時に指定する必要があるオプションを片方だけ指定した場合はエラーとなります。

Expand Down Expand Up @@ -258,7 +260,7 @@ soracom subscribers list
HTTP_PROXY=http://10.0.1.2:8080 soracom subscribers list
```

### AWS Lambda Layers
### soracom-cli の AWS Lambda Layers を利用する

soracom-cli を AWS Lambda 上で利用しようと考えたことはありますか？
Zip パッケージやコンテナイメージに soracom-cli のバイナリを含めてデプロイすることで、あなたの Lambda 関数の中から soracom-cli を呼び出すことができます。
Expand All @@ -269,21 +271,21 @@ Zip パッケージやコンテナイメージに soracom-cli のバイナリを

以下のような ARN を指定することで、あなたの Lambda 関数の中から `soracom` コマンドを実行できるようになります。

x86_64 アーキテクチャー：
- x86_64 アーキテクチャー：

```
arn:aws:lambda:ap-northeast-1:717257875195:layer:soracom-cli-${ver}:1
```
```
arn:aws:lambda:ap-northeast-1:717257875195:layer:soracom-cli-${ver}:1
```

arm64 アーキテクチャー：
- arm64 アーキテクチャー：

```
arn:aws:lambda:ap-northeast-1:717257875195:layer:soracom-cli-${ver}-arm64:1
```
```
arn:aws:lambda:ap-northeast-1:717257875195:layer:soracom-cli-${ver}-arm64:1
```

`${ver}` の部分には、対象となる soracom-cli のバージョン番号から `.` を取り除いたものが入ります。

たとえばバージョン `1.2.3` なら `123` となります。
たとえばバージョン `1.2.3` なら、`${ver}` は `123` となります。

バイナリは /bin/soracom にインストールされます。PATH が通っているので Lambda 関数の中では単に `soracom` コマンドとして実行できます。

Expand All @@ -294,6 +296,7 @@ const execSync = require('child_process').execSync;
const jpBill = execSync(`soracom --auth-key-id ${process.env.AUTH_KEY_ID} --auth-key ${process.env.AUTH_KEY} bills get-latest --coverage-type jp`).toString();
```


### トラブルシューティング

もし、以下のようなエラーメッセージが表示されてしまったら、
Expand Down Expand Up @@ -338,3 +341,11 @@ export SORACOM_AUTHKEY_ID_FOR_TEST=...
export SORACOM_AUTHKEY_FOR_TEST=...
./test/test.sh $VERSION
```

### ビルド時のトラブルシューティング

ビルド時に `go: could not create module cache: mkdir /go/pkg: permission denied` のようなエラーが表示されたときは、Docker container 内の /go/pkg の権限を確認してください。build.sh では、ホストの `${GOPATH:-$HOME/go}` を /go/pkg にマウントしているため、ホストの `$GOPATH` または `$HOME/go` の権限を確認します。ほとんどの場合は、以下のコマンドで解決できるはずです。

```
sudo chown -R $USER:$USER ${GOPATH:-$HOME/go}
```
Loading