apimetrics / apim-cli

CLI for interacting with APImetrics

APImetrics CLI

An easy way to interact with APImetrics, the unbiased SaaS Platform ensuring API products perform as agreed, are secure, meet business objectives, and comply with regulations.

• Install
  • Requirements
    • Networking
    • Supported OS & Architectures
    • Supported Node.js Versions
  • Methods
    • Using npm
    • Using Tarballs
• Usage
• Login
• Command Topics
• Environment Variables

Install

Requirements

Networking

The CLI will require an internet connection that allows access to the following domains in order to function properly. If you are adding firewall rules to allow this, we highly suggest that your firewall is configured to refresh the IP addresses for the domains on a regular basis as they may change without prior notice.

Domain	Ports
client.apimetrics.io	80, 443
auth.apimetrics.io	80, 443

Supported OS and Architectures

Both x64 and ARM architectures are supported with the following operating systems:

OS	Supported
Windows 11	✅
Windows 10	✅
Windows 7	❌
Linux	✅
macOS	✅

Supported Node.js Versions

We support all current and LTS versions of Node.js. When a version moves to end-of-life, we will drop support. If you are currently using a version of Node.js that is currently end-of-life, we suggest you upgrade to a newer version. More information about currently supported Node.js versions is published by the Node.js Release Working Group.

Version	Supported
21.x	✅
20.x	✅
18.x	✅
16.x	❌

Methods

Using npm

The CLI is built with Node.js and can be installed using npm. In order to use this method, you must have node and npm installed on your system already. You can find download instructions here. To download run the following command:

npm install -g @apimetrics/cli

Using Tarballs

These are standalone distributions containing their own Node.js binary and the CLI. They do not require any other software to already be installed on your system.

The tarballs are available in both gz and xz formats. xz is much smaller so ideal for slow connections, however gz has wider support from decompression software. If you are unsure of which to use, use gz.

To find the latest version of your desired tarball, go to our latest release.

Once you have downloaded the tarball for your system, you should then extract to a location such as /usr/local/bin/apimetrics and ensure that this location is on your PATH.

Usage

$ npm install -g @apimetrics/cli
$ apimetrics COMMAND
running command...
$ apimetrics (--version)
@apimetrics/cli/0.3.0 linux-x64 node-v21.0.0
$ apimetrics --help [COMMAND]
USAGE
  $ apimetrics COMMAND
...

Login

To start using the APImetrics CLI, you must log into your account. If you don't have an account with APImetrics, you can sign up here. To log in, run the following command:

apimetrics login

You will be redirected to a page in your browser with a code. Check this code is the same as the code displayed in your APImetrics CLI. If they are, click confirm. If you have multi-factor authentication enabled for APImetrics, you will be asked to input your one-time code. After this, you will be logged in and be able to return to your CLI.

Now that you are logged in, the CLI will ask you to select one of the Organizations you are part of to work on. Once this is selected, it will ask you to select the Project you want to work on. Now you are ready to start with your CLI.

Command Topics

• apimetrics auth - Manage authentication options.
• apimetrics calls - Manage monitoring calls.
• apimetrics config - Manage CLI configuration options.
• apimetrics help - Display help for apimetrics.
• apimetrics info - Information about APImetrics monitoring infrastructure.
• apimetrics org - Manage organization settings.
• apimetrics projects - Manage projects.
• apimetrics schedules - Manage project schedules.
• apimetrics webhooks - Manage project webhooks and alerts.
• apimetrics workflows - Manage project workflows.

Environment Variables

Name	Required	Description
APIMETRICS_API_URL	❌	Base URL for the API. Defaults to https://client.apimetrics.io/api/2/.
APIMETRICS_AUTH_SERVER	❌	OIDC server to use for login. Defaults to https://auth.apimetrics.io.
APIMETRICS_CLIENT_ID	❌	Client ID to use for OAuth based login.
APIMETRICS_CONFIG_DIR	❌	Directory to store configuration for the CLI. Defaults to ~/.config/apimetrics on UNIX and %LOCALAPPDATA%\apimetrics on Windows.
XDG_CONFIG_HOME	❌	Directory to store configuration for the CLI. Not recommended for use. Use APIMETRICS_CONFIG_DIR instead. APIMETRICS_CONFIG_DIR takes priority if also set.

apim-cli's Issues

Accept user emails as well as user IDs

Currently when doing anything with users, with the exception of invites, we must specify their ID, e.g. auth0|abc123 in order to reference them. It would be far nicer from a UX point of view if we could also use their emails as an alternative.

There are cases where multiple users will have the same email address. In situations like these, we should warn the user and force them to input an ID instead.

Improved error handling

Currently most errors are just created by throw new Error(). This means that we don't actually provide much information about errors in any structured form. A new system for handling errors should be created using custom errors and error codes in addition to have the program response codes mean something.

Delete project

Commands to add and edit projects currently exist, however there isn't one for remove projects. Something like this could be implemented:

apimetrics projects delete or when passing project ID apimetrics project delete -p abc123

A couple of notes on implementation:

1. If a user is deleting a project set as their current working project, their current working project should be reset and they should be notified.
2. If accounts or roles are still attached to the project the deletion should fail (mimic web interface) so this should be handled elegantly.

Check user is logged in for userinfo endpoint

We need to ensure that the user is actually logged in when trying to call the userinfo endpoint in the same way we validate for the ordinary API.

List users organisations

Command to get a list of organisations the current user is a member of.

DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.

A depreciation warning exists when running any command that calls an API. This was tracked to the whatwg-url module which is a dependency of node-fetch. The dependency was removed in v3.3.2 however this is an ESM module making upgrade complicated. However, this issue should be resolved by making the planned switch to http-call given in #87.

(node:15302) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
    at node:punycode:3:9
    at BuiltinModule.compileForInternalLoader (node:internal/bootstrap/realm:392:7)
    at BuiltinModule.compileForPublicLoader (node:internal/bootstrap/realm:328:10)
    at loadBuiltinModule (node:internal/modules/helpers:102:7)
    at Module._load (node:internal/modules/cjs/loader:995:17)
    at Module.require (node:internal/modules/cjs/loader:1229:19)
    at require (node:internal/modules/helpers:177:18)
    at Object.<anonymous> (/home/mnickson/source/APImetrics/APIm-CLI/node_modules/whatwg-url/lib/url-state-machine.js:2:18)
    at Module._compile (node:internal/modules/cjs/loader:1369:14)
    at Module._extensions..js (node:internal/modules/cjs/loader:1427:10)

Default to Content-Type: application/json for create call body

When we pass the body flag when creating or editing a call, the user should set the Content-Type header however it is not required so may be omitted. If it is omitted, this will cause errors in the web UI when displaying the body. If the Content-Type header is not specified, it should default to application/json when the --body option is passed.

Bug: unexpected end of config JSON

➜ apimetrics auth login 
Opening browser to https://auth.apimetrics.io/activate?user_code=VVGH-WGJX
Verification Code: VVGH-WGJX
Waiting for login... Logged in
? Select an organization APImetrics
 ›   Error: /Users/nick/.config/apimetrics/config.json: Unexpected end of JSON input

Seeing this in the publish v0.0.1 CLI

Org accounts edit user flag is not required (should be)

The --user flag on the org accounts edit command is currently not required when it should be. This should be made to be required and the example updated to reflect this.

Switch to OIDC .well-known endpoint for auth discovery

Currently all authentication endpoints are hard coded and can be overridden by environment variables. Perhaps it would be better to use the .well-known endpoint to discover the correct endpoints to call.

Schedules operations

Support for managing schedules and schedule downtimes.

Currently #9 adds support for listing schedules, however this should be expanded further to allow complete management of schedules.

Commands to add:

• Add schedule
• Remove schedule
• Modify schedule
• Add downtime to schedule
• Remove downtime from schedule

400 error on logout

We should probably check that the refresh token is a truthy value before attempting to revoke it. This should prevent 400 responses from the revoke endpoint.

https://github.com/APImetrics/APIm-CLI/blob/main/src/base-command/auth.ts#L100

Validate organisation and project ID

When a user runs config org set or config project set they can input any arbitrary value as the organisation/project ID. This is not validated and can result in a non-existent organisation/project being set for the user. This results in errors further down the line when the user tries to run commands.

Login set project fails if there is no existing project in org

When there is no pre-existing project in an organisation, the third step of the login workflow (running config:project:set) will fail as an empty array is passed to inquirer.

See SBoudrias/Inquirer.js#417 (comment) for more details.

Workflows

Implement workflow management commands. Currently list workflows is available however no other commands have yet been implemented.

Remove unused project ID flag from commands that don't need it

In some cases, the project ID flag is included when it isn't required because we are already passing the ID of an object (e.g. schedule, call). This affects at least the commands below:

• schedules:edit
• schedules:calls:add
• schedules:calls:remove

Further analysis is required to determine which other commands are affected.

Remove role from user when role has already been deleted from organisation

Following test case:

1. Add the role TEST to a user
2. Delete the role TEST from the organisation
3. Attempt to remove the role TEST from the user

Step 3 will fail with the error Error: Unrecognized role TEST as we validate all roles passed against the list of roles valid for the organisation. To prevent this issue, we should instead validate the list of roles to remove against the list of roles assigned to the user.

Personal Projects

Personal projects require special handling. Currently many commands work on the assumption that this is an org and make calls as such. Most commands check to see if the current org is set. When the user has selected personal projects, the current org is set to "", hence these checks fail and the user is asked to set their org.

Also need to improve error messages for features that are not available for personal projects.

List all users on a project

Currently the projects accounts command only lists users with direct access to a given project and does not include any users who have access through a given role. This is at odds with the web interface which displays everyone who has access, including those with access as a result of roles.

CLI should be changed to reflect the web interface format.

Fallback to IPv4 when making API calls

Currently there is no retry mechanism for making API calls. This means that if the request encounters some form of network error, the call will fail without any attempt to retry. Perhaps the most obvious instance of this is when the interface being used has an IPv6 address assigned, but the destination host is unreachable. This will result in an error such as this one

./bin/run login
 ›   Error: request to https://auth.apimetrics.io/oauth/device/code failed, reason: connect EHOSTUNREACH 2606:4700::6810:d8f1:443

The requests should at least make an attempt to fall back to IPv4 for requests when needed.

Environment Variables

Add support for setting environments and environment variables.

Whoami Command

Add a command that tells the user their current logged in account, current working organisation and current working project.

Show project name for whoami command

Currently only the project ID is shown when the apimetrics info whoami. It would be nice from a user point of view to also be able to show the name of the project as well. This would probably involve an extra API call to get the name.