diff --git a/mint.json b/mint.json index aa1919a8..8f51257e 100644 --- a/mint.json +++ b/mint.json @@ -69,6 +69,11 @@ "url": "v2/apps", "version": "Version 2.0" }, + { + "name": "Cobo CLI", + "url": "v2/cobo-cli", + "version": "Version 2.0" + }, { "name": "Documentation", "url": "v1/overview", @@ -455,6 +460,83 @@ ], "version": "Version 2.0" }, + { + "group": "Cobo CLI", + "pages": [ + { + "group": "Overview", + "pages": [ + "v2/cobo-cli/overview/introduction", + "v2/cobo-cli/overview/changelog" + ] + }, + { + "group": "Get Started", + "pages": [ + "v2/cobo-cli/get-started/installation", + "v2/cobo-cli/get-started/login-and-authentication", + "v2/cobo-cli/get-started/environment-management", + "v2/cobo-cli/get-started/key-management", + "v2/cobo-cli/get-started/configuration", + "v2/cobo-cli/get-started/global-options" + ] + }, + { + "group": "Utility Commands", + "pages": [ + "v2/cobo-cli/utility-commands/real-time-logs", + "v2/cobo-cli/utility-commands/open-browser-shortcuts", + "v2/cobo-cli/utility-commands/version-and-updates", + "v2/cobo-cli/utility-commands/api-documentation" + ] + }, + { + "group": "API Commands", + "pages": [ + "v2/cobo-cli/api-commands/get-requests", + "v2/cobo-cli/api-commands/post-requests", + "v2/cobo-cli/api-commands/put-requests", + "v2/cobo-cli/api-commands/delete-requests" + ] + }, + { + "group": "GraphQL", + "pages": [ + "v2/cobo-cli/graphql/graphql-queries" + ] + }, + { + "group": "Webhooks", + "pages": [ + "v2/cobo-cli/webhooks/listen-and-forward-events", + "v2/cobo-cli/webhooks/trigger-events" + ] + }, + { + "group": "App Development", + "pages": [ + "v2/cobo-cli/app-development/init-app", + "v2/cobo-cli/app-development/run-app-locally", + "v2/cobo-cli/app-development/publish-app", + "v2/cobo-cli/app-development/update-app" + ] + }, + { + "group": "Workflows", + "pages": [ + "v2/cobo-cli/workflows/create-and-publish-app", + "v2/cobo-cli/workflows/api-integration-example" + ] + }, + { + "group": "Reference", + "pages": [ + "v2/cobo-cli/reference/cli-commands" + ] + } + ], + "version": "Version 2.0" + }, { "group": "Overview", "pages": [ diff --git a/v2/cobo-cli/api-commands/delete-requests.mdx b/v2/cobo-cli/api-commands/delete-requests.mdx new file mode 100644 index 00000000..3ecbd028 --- /dev/null +++ b/v2/cobo-cli/api-commands/delete-requests.mdx @@ -0,0 +1,60 @@ +--- +title: "DELETE Requests" +--- + +The `cobo delete` command allows you to make DELETE requests to Cobo API +endpoints. This command is useful for removing resources from the Cobo WaaS 2 +API. + +## Usage + +```bash +$ cobo delete [options] +``` + +## Options + +- `-d, --describe`: Display operation description +- `-l, --list`: List all API operations for this method + +## Examples + +### List all DELETE operations + +To see a list of all available DELETE operations: + +```bash +$ cobo delete -l +``` + +### Delete a webhook endpoint + +To delete a specific webhook endpoint: + +```bash +$ cobo delete /webhooks/{webhook_id} --webhook_id your_webhook_id +``` + +### Remove a key share holder + +To remove a key share holder from a group: + +```bash +$ cobo delete /wallets/mpc/key_share_holder_groups/{group_id}/key_share_holders/{holder_id} --group_id your_group_id --holder_id your_holder_id +``` + +### Get operation description + +To see the description of a specific DELETE operation: + +```bash +$ cobo delete /webhooks/{webhook_id} -d +``` + +## API Reference + +For a complete list of available DELETE endpoints and their parameters, refer to the [Cobo WaaS 2 API Documentation](https://www.cobo.com/developers/v2/api-references/). + + +Remember to authenticate your requests by logging in or setting up your API keys before making API calls. + \ No newline at end of file diff --git a/v2/cobo-cli/api-commands/get-requests.mdx b/v2/cobo-cli/api-commands/get-requests.mdx new file mode 100644 index 00000000..49c80fcb --- /dev/null +++ b/v2/cobo-cli/api-commands/get-requests.mdx @@ -0,0 +1,60 @@ +--- +title: "GET Requests" +--- + +The `cobo get` command allows you to make GET requests to Cobo API endpoints. +This command is useful for retrieving information from the Cobo WaaS 2 API. + +## Usage + +```bash +$ cobo get [options] +``` + +## Options + +- `-d, --describe`: Display operation description +- `-l, --list`: List all API operations for this method + +## Examples + +### List all GET operations + +To see a list of all available GET operations: + +```bash +$ cobo get -l +``` + + +### Retrieve wallet information + +To get information about a specific wallet: + +```bash +$ cobo get /wallets/{wallet_id} --wallet_id your_wallet_id +``` + +### List all transactions + +To retrieve a list of all transactions: + +```bash +$ cobo get /transactions +``` + +### Get operation description + +To see the description of a specific GET operation: + +```bash +$ cobo get /wallets/{wallet_id} -d +``` + +## API Reference + +For a complete list of available GET endpoints and their parameters, refer to the [Cobo WaaS 2 API Documentation](https://www.cobo.com/developers/v2/api-references/). + + +Remember to authenticate your requests by logging in or setting up your API keys before making API calls. + \ No newline at end of file diff --git a/v2/cobo-cli/api-commands/post-requests.mdx b/v2/cobo-cli/api-commands/post-requests.mdx new file mode 100644 index 00000000..0be183b2 --- /dev/null +++ b/v2/cobo-cli/api-commands/post-requests.mdx @@ -0,0 +1,60 @@ +--- +title: "POST Requests" +--- + +The `cobo post` command allows you to make POST requests to Cobo API endpoints. +This command is useful for creating new resources or submitting data to the Cobo +WaaS 2 API. + +## Usage + +```bash +$ cobo post [options] +``` + +## Options + +- `-d, --describe`: Display operation description +- `-l, --list`: List all API operations for this method + +## Examples + +### List all POST operations + +To see a list of all available POST operations: + +```bash +$ cobo post -l +``` + +### Create a new wallet + +To create a new wallet: + +```bash +$ cobo post /wallets --name "My New Wallet" --wallet_type Custodial +``` + +### Initiate a transaction + +To initiate a new transaction: + +```bash +$ cobo post /transactions --from_wallet_id your_wallet_id --to_address recipient_address --amount 1.5 --token_id BTC +``` + +### Get operation description + +To see the description of a specific POST operation: + +```bash +$ cobo post /wallets -d +``` + +## API Reference + +For a complete list of available POST endpoints and their parameters, refer to the [Cobo WaaS 2 API Documentation](https://www.cobo.com/developers/v2/api-references/). + + +Remember to authenticate your requests by logging in or setting up your API keys before making API calls. + \ No newline at end of file diff --git a/v2/cobo-cli/api-commands/put-requests.mdx b/v2/cobo-cli/api-commands/put-requests.mdx new file mode 100644 index 00000000..6bba42c7 --- /dev/null +++ b/v2/cobo-cli/api-commands/put-requests.mdx @@ -0,0 +1,59 @@ +--- +title: "PUT Requests" +--- + +The `cobo put` command allows you to make PUT requests to Cobo API endpoints. +This command is useful for updating existing resources in the Cobo WaaS 2 API. + +## Usage + +```bash +$ cobo put [options] +``` + +## Options + +- `-d, --describe`: Display operation description +- `-l, --list`: List all API operations for this method + +## Examples + +### List all PUT operations + +To see a list of all available PUT operations: + +```bash +$ cobo put -l +``` + +### Update wallet information + +To update information for a specific wallet: + +```bash +$ cobo put /wallets/{wallet_id} --wallet_id your_wallet_id --name "Updated Wallet Name" +``` + +### Update transaction status + +To update the status of a transaction: + +```bash +$ cobo put /transactions/{transaction_id} --transaction_id your_transaction_id --status Completed +``` + +### Get operation description + +To see the description of a specific PUT operation: + +```bash +$ cobo put /wallets/{wallet_id} -d +``` + +## API Reference + +For a complete list of available PUT endpoints and their parameters, refer to the [Cobo WaaS 2 API Documentation](https://www.cobo.com/developers/v2/api-references/). + + +Remember to authenticate your requests by logging in or setting up your API keys before making API calls. + \ No newline at end of file diff --git a/v2/cobo-cli/get-started/configuration.mdx b/v2/cobo-cli/get-started/configuration.mdx new file mode 100644 index 00000000..00576aed --- /dev/null +++ b/v2/cobo-cli/get-started/configuration.mdx @@ -0,0 +1,95 @@ +--- +title: "Configuring Cobo CLI" +--- + +This guide introduces how to inspect and modify the configuration of the Cobo +CLI. The configuration is used by various Cobo CLI commands, including `cobo +env`, `cobo auth`, and `cobo keys`, to store and retrieve their respective +information. + +By following this guide, you will be able to: + +1. Understand the configuration file location and its purpose +2. Set configuration values +3. Retrieve configuration values +4. List all configurations +5. Delete configuration values +6. Manage important settings like environment and authentication method + +## Prerequisites + +- You have installed the Cobo CLI on your system. If not, refer to the [Installation guide](/v2/cobo-cli/get-started/installation). + +## 1. Configuration File Location and Purpose + +By default, the Cobo CLI stores its configuration in a `.env` file within the `.cobo` directory in your home directory (`~/.cobo/.env`). This file is used to store various settings that are used across different Cobo CLI commands. + +You can override this location by setting the `COBO_ENV` environment variable to a different path. + +## 2. Set Configuration Values + +To set a configuration value, use the `set` subcommand of the `config` command: + +```bash +$ cobo config set +``` + +## 3. Retrieve Configuration Values + +To retrieve a configuration value, use the `get` subcommand: + +```bash +$ cobo config get +``` + +If the configuration key exists, it will display the value. Otherwise, it will inform you that the configuration was not found. + +## 4. List All Configurations + +To see all your current configuration settings, use the `list` subcommand: + +```bash +$ cobo config list +``` + +This will display all key-value pairs in your configuration. + +## 5. Delete Configuration Values + +To remove a configuration value, use the `delete` subcommand: + +```bash +$ cobo config delete +``` + +## 6. Important Configuration Settings + +While you can store any custom configuration values, there are some key settings that the Cobo CLI uses: + +### Environment + +The Cobo CLI supports three environments: +- `sandbox`: For testing and development +- `dev`: For development purposes +- `prod`: For production use + +```bash +$ cobo config set environment sandbox +``` + +This has the same effect as running `cobo env sandbox`. + + +### Authentication Method + +The CLI supports three authentication methods: +- `apikey`: For API key-based authentication +- `user`: For user-based authentication +- `org`: For organization-based authentication + +```bash +$ cobo config set auth_method apikey +``` + +This has the same effect as running `cobo auth apikey`. + diff --git a/v2/cobo-cli/get-started/environment-management.mdx b/v2/cobo-cli/get-started/environment-management.mdx new file mode 100644 index 00000000..9cbd3e9d --- /dev/null +++ b/v2/cobo-cli/get-started/environment-management.mdx @@ -0,0 +1,65 @@ +--- +title: "Environment Management" +--- + +Cobo CLI allows you to switch between different environments, such as sandbox, +development, and production. This guide helps you set up and switch between +environments effectively. + +## View Current Environment + +To check which environment is currently active, use: + +```bash +$ cobo env +Current environment: dev +``` + +This command will display the name of the currently active environment. + + +If you don't specify an environment, Cobo CLI defaults to the "development" environment. + + +## Set Environment + +To switch to a different environment, use the following command: + +```bash +$ cobo env +``` + +Replace `` with your desired environment (e.g., "dev" or +"prod"). This command will set the specified environment as the active one for +subsequent CLI commands. + +## Global Environment Option + +You can override the current environment for a single command by using the +global `-e` or `--env` option: + +```bash +$ cobo -e +``` + +This allows you to execute a command in a specific environment without changing the overall active environment. + +## Environment Configuration + +Each environment has pre-configured API endpoints and base URLs for the Cobo portal. These configurations are set as follows: + +- Sandbox: + - API Host: https://api.sandbox.cobo.com + - Base URL: https://portal.sandbox.cobo.com + +- Development: + - API Host: https://api.dev.cobo.com + - Base URL: https://portal.dev.cobo.com + +- Production: + - API Host: https://api.cobo.com + - Base URL: https://portal.cobo.com + + +Remember to switch to the correct environment before executing commands to avoid unintended actions in the wrong environment. + \ No newline at end of file diff --git a/v2/cobo-cli/get-started/global-options.mdx b/v2/cobo-cli/get-started/global-options.mdx new file mode 100644 index 00000000..e3656754 --- /dev/null +++ b/v2/cobo-cli/get-started/global-options.mdx @@ -0,0 +1,110 @@ +--- +title: 'Global Options' +--- + +Cobo CLI provides several global options that can be used with any command to customize its behavior. These options allow you to control the environment, authentication method, and other settings for your CLI operations. + +## Available Global Options + +### Environment Selection (-e, --env) + +The `-e` or `--env` option allows you to override the default environment for a specific command. + +Usage: + +```bash +$ cobo -e sandbox get /wallets +``` + +Possible values include: +- `sandbox`: Sandbox environment +- `dev`: Development environment +- `prod`: Production environment + +If not specified, the CLI will use the environment set in your configuration or default to the development environment. + +### Authentication Method (-a, --auth) + +The `-a` or `--auth` option allows you to override the default authentication method for a specific command. + +Usage: + +```bash +$ cobo -a user get /wallets +``` + +Possible values include: +- `apikey`: Use API key authentication +- `user`: Use user-based authentication +- `org`: Use organization-based authentication + +If not specified, the CLI will use the authentication method set in your configuration or default to API key authentication. + +### Debug Mode (--enable-debug) + +The `--enable-debug` flag enables debug mode, which provides verbose logging for troubleshooting purposes. + +Usage: + +```bash +$ cobo --enable-debug get /wallets +``` + +### Custom Environment File (--env-file) + +The `--env-file` option allows you to specify a custom path for the .env file containing your environment variables. + +Usage: + +```bash +$ cobo-cli --env-file /path/to/custom/.env get /wallets +``` + +If not specified, the CLI will use the default .env file located in your Cobo CLI configuration directory. + +### Custom API Specification (--spec) + +The `--spec` option allows you to specify a custom OpenAPI specification file for the Cobo API. + +Usage: + +```bash +$ cobo --spec /path/to/custom/openapi.yaml get /wallets +``` + +This option is useful when you need to work with a different version of the API or when testing against a modified API specification. + +## Combining Global Options + +You can combine multiple global options in a single command: + +```bash +$ cobo -e prod -a user --enable-debug --spec /path/to/custom/openapi.yaml get /wallets +``` + +This command will: +1. Use the production environment +2. Authenticate using user-based authentication +3. Enable debug mode for verbose logging +4. Use a custom API specification file +5. Execute the GET request to retrieve wallet information + +## Configuration Precedence + +The Cobo CLI follows this order of precedence when determining which settings to use: + +1. Command-line options (highest priority) +2. Environment variables +3. Configuration file settings +4. Default values (lowest priority) + +This allows you to easily override settings on a per-command basis without modifying your configuration files. + + +Global options should be placed before the specific command you want to run. For example, `-e sandbox` should come before `get /wallets`. + + +By using these global options, you can flexibly control the behavior of the Cobo +CLI across different environments, authentication methods, and API +specifications, making it easier to manage your workflows and integrate with +various Cobo services. diff --git a/v2/cobo-cli/get-started/installation.mdx b/v2/cobo-cli/get-started/installation.mdx new file mode 100644 index 00000000..767b6a0c --- /dev/null +++ b/v2/cobo-cli/get-started/installation.mdx @@ -0,0 +1,49 @@ +--- +title: "Installation" +--- + +This guide will help you install the Cobo CLI on your local machine. The Cobo +CLI is a powerful tool that allows you to interact with Cobo WaaS 2 services +directly from your terminal. + +## System requirements + +The Cobo CLI is supported on most operating systems. Ensure your system meets +the following requirements: + +- macOS (10.14 Mojave or later) +- Windows 10 or later +- Linux (most distributions supported) + +## Install the Cobo CLI + +Choose the installation method that best suits your operating system: + +### Using pip (recommended) + +You can install the Cobo CLI using pip, which works on all supported operating systems: + +```bash +$ pip install cobo-cli +``` + +### macOS + +You can install the Cobo CLI on macOS using Homebrew: + +```bash +$ brew install cobo/cobo-cli +``` + + +## Verify the installation + +To verify that the Cobo CLI has been installed correctly, open a new terminal + +```bash +$ cobo version +``` + +## Next steps + +Now that you have the Cobo CLI installed, you're ready to [log in and authenticate](/v2/cobo-cli/get-started/login-and-authentication) with your Cobo account. \ No newline at end of file diff --git a/v2/cobo-cli/get-started/key-management.mdx b/v2/cobo-cli/get-started/key-management.mdx new file mode 100644 index 00000000..d948d788 --- /dev/null +++ b/v2/cobo-cli/get-started/key-management.mdx @@ -0,0 +1,99 @@ +--- +title: "Key Management" +--- + +This guide explains how to generate and manage API and APP keys using the Cobo +CLI. Proper key management is crucial for secure access to Cobo WaaS 2.0 +services and efficient application development. + +## Generate Keys + +To generate a new API or APP key pair, use the `keys generate` command: + +```bash +$ cobo keys generate [OPTIONS] +``` + +### Options + +- `--key-type`: Specify the type of key to generate (API or APP). Default is API. +- `--alg`: Specify the key generation algorithm. Default is ed25519. +- `--force`: Force replacement of existing keys. + +### Examples + +Generate a new API key pair: + +```bash +$ cobo keys generate +``` + +Generate a new APP key pair: + +```bash +$ cobo keys generate --key-type APP +``` + +Generate a new API key pair with a specific algorithm: + +```bash +$ cobo keys generate --alg rsa +``` + +Force replacement of existing API keys: + +```bash +$ cobo keys generate --force +``` + +## Key Storage + +Generated keys are securely stored in your environment file (default: ~/.cobo/.env). The public key is stored as `__KEY`, and the secret key is stored as `__SECRET`. + + +Never share your secret key. Keep it secure and use only the public key when configuring API access in the Cobo Portal. + + +## Using API Keys for Authentication + +After generating an API key pair, follow these steps to use it for authentication with the Cobo CLI: + +1. Switch to API key authentication using the following command: + +```bash +$ cobo auth apikey +``` + +This sets the authentication method to use the API key stored in your environment file. + +2. Add the newly generated API key to the Cobo Portal: + - Log in to the Cobo Portal and navigate to the developer console. + - Find the API Key Management page. + - Add the newly generated API key (use the public key). + - Grant the API key appropriate wallet scope, roles, and permissions. + + +You can quickly access the developer console by using the `cobo open developer` +command. This shortcut opens your browser and takes you directly to the right +page in the Cobo Portal. For more information on browser shortcuts, see the +[Open Browser Shortcuts](/v2/cobo-cli/utility-commands/open-browser-shortcuts) +guide. + + + +Ensure you grant only the necessary permissions to your API key. Limiting access helps maintain the security of your account and resources. + + +3. Once you've added the API key to the Cobo Portal and set the appropriate permissions, your Cobo CLI will be able to authenticate using this key for subsequent operations. + + +Remember to update the API key in the Cobo Portal's API Key management console every time you generate a new key pair using the CLI. + + +## Best Practices + +- Regularly rotate your API and APP keys to maintain security. +- Use different keys for different environments (development, sandbox, production). +- Limit the permissions associated with each key to the minimum required for its intended use. +- Monitor key usage and revoke any keys that may have been compromised. + diff --git a/v2/cobo-cli/get-started/login-and-authentication.mdx b/v2/cobo-cli/get-started/login-and-authentication.mdx new file mode 100644 index 00000000..f9150f06 --- /dev/null +++ b/v2/cobo-cli/get-started/login-and-authentication.mdx @@ -0,0 +1,112 @@ +--- +title: "Login and Authentication" +--- + +This guide will walk you through the process of logging in, authenticating, and +managing authentication methods with the Cobo CLI. Proper authentication is +essential for securely accessing Cobo WaaS 2.0 services and managing your +resources. + +## Authentication Methods + +Cobo CLI supports three authentication methods: + +1. API Key +2. User Access Token +3. Organization Access Token + +You can switch between these methods using the `auth` command. + +## User Login + +To log in as a user and obtain a user access token, use the following command: + +``` +cobo login --user +``` + +This command will initiate the user login process: + +1. The CLI will display a browser URL, a token URL, and a code. +2. You'll be prompted to open a browser to continue the authorization process. +3. If you confirm, your default browser will open with the provided URL. +4. Complete the authorization process in your browser, granting the necessary permissions for the Cobo CLI app to access your crypto wallets. +5. The CLI will poll the token URL for the granted token. +6. Once authenticated, your user access token will be saved in the environment file (default: ~/.cobo/.env). + +## Organization Login + +To log in as an organization and obtain an organization access token, use the following command: + +``` +cobo login --org --org-uuid +``` + +Replace `` with your actual organization UUID. + +This command will: + +1. Prompt you to open a browser for authorization. +2. Guide you through the process of granting permissions for the Cobo CLI app to access your organization's resources. +3. Retrieve and save the organization token in the environment file. + +## Refreshing Organization Token + +To refresh an existing organization token, add the `--refresh-token` flag: + +```bash +$ cobo login --org --org-uuid --refresh-token +``` + +This command will refresh the existing token for the specified organization and update it in the environment file. + +## Logout + +To remove the access tokens obtained via login, use the logout command: + +```bash +$ cobo logout +``` + +You can specify which tokens to remove: + +- `cobo logout --user`: Remove only the user access token +- `cobo logout --org`: Remove only the organization access token +- `cobo logout --all`: Remove both user and organization access tokens (default behavior) + +## Switching Authentication Methods + +To switch between authentication methods, use the `auth` command: + +```bash +$ cobo auth +``` + +Replace `` with one of the following: + +- `apikey`: Use API Key authentication +- `user`: Use User Access Token authentication +- `org`: Use Organization Access Token authentication + +For example, to switch to API Key authentication: + +```bash +$ cobo auth apikey +``` + +To view the current authentication method: + +```bash +$ cobo auth +``` + +## API Key Authentication + +For information on generating and managing API keys, please refer to the [Key Management](/v2/cobo-cli/get-started/key-management) guide. + +## Best Practices + +- Keep your credentials and access tokens secure and never share them. +- Use environment variables or a secure configuration file to store sensitive information. +- Regularly refresh your tokens and rotate your API keys to maintain security. +- Use the appropriate authentication method based on your use case and security requirements. diff --git a/v2/cobo-cli/graphql/graphql-queries.mdx b/v2/cobo-cli/graphql/graphql-queries.mdx new file mode 100644 index 00000000..173d67ad --- /dev/null +++ b/v2/cobo-cli/graphql/graphql-queries.mdx @@ -0,0 +1,155 @@ +--- +title: "GraphQL Queries" +description: "Execute GraphQL queries using the Cobo CLI" +--- + +The Cobo CLI provides a powerful GraphQL interface to interact with the Cobo WaaS 2 API. This feature allows you to execute complex queries and retrieve specific data from the API. + +## Execute a GraphQL Query + +To execute a GraphQL query, use the `graphql` command followed by your query. The basic syntax is: + +```bash +$ cobo graphql -q "YOUR_QUERY_HERE" +``` + +Replace `YOUR_QUERY_HERE` with your actual GraphQL query. + +## Query Structure + +Your GraphQL query should be a valid JSON string containing a `query` key. For example: + +```bash +$ cobo graphql -q '{ + "query": "{ wallets { id name } }" +}' +``` + +If your query is a simple string (not JSON), the CLI will automatically wrap it in the required JSON structure. + +## Use Variables + +You can include variables in your GraphQL query using the `-v` or `--variables` option. The variables should be provided as a JSON string. For example: + +```bash +$ cobo graphql -q '{ + "query": "query($walletId: ID!) { wallet(id: $walletId) { id name balance } }" +}' -v '{ + "walletId": "f47ac10b-58cc-4372-a567-0e02b2c3d479" +}' +``` + +## Raw Output + +By default, the CLI formats the JSON response for readability. If you prefer the raw JSON output, use the `--raw` flag: + +```bash +$ cobo graphql -q "{ wallets { id name } }" --raw +``` + +## Example Queries + +Here are some example GraphQL queries you can try with the Cobo WaaS 2 API: + +### Fetch Wallet Information + +```bash +$ cobo graphql -q '{ + "query": " + { + wallet(id: \"f47ac10b-58cc-4372-a567-0e02b2c3d479\") { + id + name + walletType + balance { + tokenId + amount + } + } + } + " +}' +``` + +### Retrieve Transactions for a Wallet + +```bash +$ cobo graphql -q '{ + "query": " + { + transactions(walletId: \"f47ac10b-58cc-4372-a567-0e02b2c3d479\", limit: 5) { + id + type + status + amount { + tokenId + value + } + } + } + " +}' +``` + +### Get MPC Vault Information with Variables + +```bash +$ cobo graphql -q '{ + "query": " + query($vaultId: ID!) { + mpcVault(id: $vaultId) { + id + name + type + rootPubkeys { + rootPubkey + curve + } + } + } + " +}' -v '{ + "vaultId": "YPdbyVaVGqXXjkUsohHw" +}' +``` + +## Error Handling + +If there's an error in your GraphQL query or during execution, the CLI will display the error message. Make sure to check the response for any error fields. + + +Always validate your queries before executing them in a production environment to avoid potential issues. + + +## Tips for Using GraphQL with Cobo CLI + +1. Use the `--help` option with the `graphql` command to see all available options: + + ```bash + $ cobo graphql --help + ``` + +2. For complex queries, consider writing your query in a separate file and using command substitution to pass it to the CLI: + + ```bash + $ cobo graphql -q "$(cat your_query.graphql)" + ``` + +3. Remember to escape special characters in your query string when using it directly in the command line. + +4. The GraphQL endpoint uses the same authentication method as other API commands. Ensure you're properly authenticated before executing queries. + +5. Use the Cobo WaaS 2 API documentation to explore available GraphQL schemas and construct your queries accordingly. + + +By leveraging the power of GraphQL, you can efficiently retrieve exactly the data you need from the Cobo WaaS 2 API, reducing unnecessary data transfer and simplifying your API interactions. + + +## Related Commands + +- [`cobo get`](/v2/cobo-cli/api-commands/get-requests): Execute GET requests to the Cobo API +- [`cobo post`](/v2/cobo-cli/api-commands/post-requests): Execute POST requests to the Cobo API +- [`cobo put`](/v2/cobo-cli/api-commands/put-requests): Execute PUT requests to the Cobo API +- [`cobo delete`](/v2/cobo-cli/api-commands/delete-requests): Execute DELETE requests to the Cobo API + +For more information on these commands, refer to their respective documentation pages. diff --git a/v2/cobo-cli/overview/introduction.mdx b/v2/cobo-cli/overview/introduction.mdx new file mode 100644 index 00000000..e35d4b21 --- /dev/null +++ b/v2/cobo-cli/overview/introduction.mdx @@ -0,0 +1,103 @@ +--- +title: "Introduction to Cobo CLI" +--- + +The Cobo Command Line Interface (CLI) is a powerful developer tool designed to +help you build, test, and manage your integration with Cobo WaaS 2.0 directly +from the command line. With Cobo CLI, you can easily perform many common tasks +such as calling Cobo APIs, testing your webhooks integration, and managing your +wallets and transactions. + +## Example usage + +Here are some quick examples of how to use Cobo CLI: + +1. List all Custodial Wallets: + +```bash +$ cobo get /wallets --wallet_type Custodial +``` + +2. Use GraphQL to query Cobo WaaS: + +```bash +$ cobo graphql -q '{ + wallets(first: 5) { + edges { + node { + id + name + type + } + } + } +}' +``` + +3. Create a new Cobo application using a template: + +```bash +$ cobo app init -f nextjs -d my-cobo-app +``` + +4. Look up documentation for a specific API endpoint: + +```bash +$ cobo doc /wallets/{wallet_id}/utxos +``` + +5. Monitor real-time API requests: + +```bash +$ cobo logs tail --http-method GET --request-path /wallets +``` + +6. Trigger a webhook event: + +```bash +$ cobo webhook trigger wallets.transaction.updated --override-data '{"wallet_id": "1234567890"}' +``` + +7. Listen for webhook events and forward them to a local endpoint: + +```bash +$ cobo webhook listen --events wallets.transaction.updated --forward http://localhost:9988 +``` + +These examples demonstrate some of the key functionalities of Cobo CLI, including REST API interactions, GraphQL queries, application management, accessing API documentation, real-time log monitoring, and webhook event handling. + + +## Key features + +- **API interaction**: Easily interact with Cobo WaaS 2.0 through RESTful and GraphQL based APIs directly from your terminal. +- **API documentation lookup**: Access helpful documentation for all Cobo WaaS APIs, requests, responses, and their parameters directly from the command line. +- **Cobo Portal Applications**: Build, manage, and publish Cobo Portal Applications, including creating apps from various application templates for different programming languages and frameworks. +- **Real-time API monitoring**: Stream API request logs for quick debugging and monitoring. +- **Webhook testing**: Test and debug your webhook integrations locally. (Coming soon) +- **Multiple authentication methods**: Utilize and test three types of authentication mechanisms: API keys, user access tokens, and org access tokens. +- **Environment switching**: Seamlessly switch between sandbox, development, and production environments for development and testing. +- **Autocompletion**: Enable autocompletion for faster command input and improved productivity. + +## Use cases + +Cobo CLI is particularly useful for: + +- Developers integrating Cobo WaaS 2.0 into their applications +- DevOps engineers managing Cobo resources and monitoring transactions +- QA teams testing Cobo integrations and API responses +- Support teams troubleshooting customer issues related to Cobo services + +## Getting started + +To begin using Cobo CLI, follow these steps: + +1. [Install Cobo CLI](/v2/cobo-cli/get-started/installation) on your system. +2. [Log in and authenticate](/v2/cobo-cli/get-started/login-and-authentication) your Cobo account. +3. [Configure your environment](/v2/cobo-cli/get-started/environment-management) for development or production use. +4. Start exploring Cobo CLI commands to manage your wallets and transactions. + + +Cobo CLI is designed for use in test mode by default. Always exercise caution +when using it in a production environment, and ensure you understand the +implications of each command before execution. + diff --git a/v2/cobo-cli/reference/cli-commands.mdx b/v2/cobo-cli/reference/cli-commands.mdx new file mode 100644 index 00000000..58ca4078 --- /dev/null +++ b/v2/cobo-cli/reference/cli-commands.mdx @@ -0,0 +1,293 @@ +--- +title: 'CLI Commands Reference' +description: 'A comprehensive guide to all commands supported by Cobo CLI' +--- + +This document provides a detailed reference for all commands supported by the +Cobo CLI tool. Each command is explained with its purpose, options, and usage +examples. + +## Global Options + +The following options can be used with any command: + +- `-e, --env`: Override the environment for this command. Choices are [development, sandbox, production]. +- `-a, --auth`: Override the authentication method for this command. Choices are [apikey, oauth]. +- `--enable-debug`: Enable debug mode for verbose logging. +- `--env-file`: Specify the path to the dotenv file. Default is ~/.cobo/.env. +- `--spec`: Path to a custom OpenAPI specification file. + +## Main Commands + +### version + +Display the current version of the Cobo CLI tool. + +Usage: +```bash +$ cobo version +``` + +### config + +Manage CLI configuration settings. + +Subcommands: +- `set `: Set a configuration value. +- `get `: Get a configuration value. +- `list`: List all configuration values. +- `delete `: Delete a configuration value. + +Usage: +```bash +$ cobo config set api_key your_api_key +$ cobo config get api_key +$ cobo config list +$ cobo config delete api_key +``` + +### login + +Perform user or organization login operations. + +Options: +- `--user, -u`: Login action associated with user dimension (default). +- `--org, -o`: Login action associated with organization dimension. +- `--org-uuid`: Specify the organization ID used to retrieve the token (required for organization login). +- `--refresh-token`: Refresh the existing token instead of generating a new one. + +Usage: +```bash +$ cobo login +$ cobo login --org --org-uuid your_org_uuid +``` + +### logout + +Perform user or organization logout operations. + +Options: +- `--user, -u`: Logout action associated with user dimension. +- `--org, -o`: Logout action associated with organization dimension. +- `--all, -a`: Logout action for both user and organization (default). + +Usage: +```bash +$ cobo logout +$ cobo logout --user +$ cobo logout --org +``` + +### keys + +Commands to generate and manage API/APP keys. + +Subcommands: +- `generate`: Generate a new API/APP key pair. + +Options for generate: +- `--key-type`: Type of key to generate (API or APP). Default is API. +- `--alg`: Specify the key generation algorithm. Default is ed25519. +- `--force`: Force to replace existing keys. + +Usage: +```bash +$ cobo keys generate +$ cobo keys generate --key-type APP --alg rsa --force +``` + +### app + +Commands to create, run, publish, and manage Cobo applications. + +Subcommands: +- `init`: Create a new Cobo application from template. +- `run`: Run a Cobo application. +- `publish`: Publish a Cobo application. +- `update`: Update a Cobo application. +- `status`: Check the status of a Cobo application. + +Usage: +```bash +$ cobo app init -f nextjs -d my_app +$ cobo app run -p 3000 +$ cobo app publish +$ cobo app update +$ cobo app status +``` + +### open + +Open a specific Cobo portal page in the default web browser. + +Arguments: +- `target`: The page to open. Choices are [portal, dashboard, wallets, custodial, mpc, scw, exchange, developer, apps, settings, guides, pricing, approval]. Default is portal. + +Usage: +```bash +$ cobo open dashboard +$ cobo open developer +``` + +### doc + +Open Cobo documentation or display API operation information. + +Arguments: +- `topic_or_path`: The documentation topic or API path to open/display. + +Options: +- `-u, --update`: Update the OpenAPI specification. + +Usage: +```bash +$ cobo doc api +$ cobo doc /v2/custody/new_address +$ cobo doc -u +``` + +### env + +Set or view the current environment. + +Arguments: +- `environment`: The environment to set. Choices are [development, sandbox, production]. + +Usage: +```bash +$ cobo env prod +$ cobo env +``` + +### auth + +Set or view the default authentication method. + +Arguments: +- `method`: The authentication method to set. Choices are [apikey, oauth]. + +Usage: +```bash +$ cobo auth apikey +$ cobo auth +``` + +## API Commands + +### get + +Make a GET request to a Cobo API endpoint. + +Usage: +```bash +$ cobo get /wallets --wallet_type Custodial +``` + + +### post + +Make a POST request to a Cobo API endpoint. + +Usage: +```bash +$ cobo post /wallets --name "My New Wallet" --wallet_type Custodial +``` + +### put + +Make a PUT request to a Cobo API endpoint. + +Usage: +```bash +$ cobo put /wallets/{wallet_id} --wallet_id your_wallet_id --name "Updated Wallet Name" +``` + +### delete + +Make a DELETE request to a Cobo API endpoint. + +Usage: +```bash +$ cobo delete /wallets/mpc/key_share_holder_groups/{group_id}/key_share_holders/{holder_id} --group_id your_group_id --holder_id your_holder_id +``` + +### graphql + +Execute a GraphQL query against the Cobo API. + +Options: +- `-q, --query`: The GraphQL query string (required). +- `-v, --variables`: JSON string of variables for the GraphQL query. +- `--raw`: Output the raw JSON response. + +Usage: +```bash +$ cobo graphql -q '{ + "query": " + { + wallet(id: \"f47ac10b-58cc-4372-a567-0e02b2c3d479\") { + id + name + walletType + balance { + tokenId + amount + } + } + } + " +}' +``` + +## Utility Commands + +### logs tail + +Tail the request logs from Cobo. + +Options: +- `--http-method`: Filter logs by HTTP method. +- `--request-path`: Filter logs by request path. +- `--status-code`: Filter logs by status code. +- `--api-key`: Filter logs by API key. +- `--ip-address`: Filter logs by IP address. +- `--limit`: Number of logs to fetch per request (default: 3). + +Usage: +```bash +$ cobo logs tail --http-method GET --request-path /v2/custody/coin_info --limit 5 +``` + +### webhook + +Commands related to webhook operations. + +Subcommands: +- `trigger`: Manually trigger a webhook event. +- `events`: List all available webhook event types. +- `listen`: Listen for webhook events using WebSocket. + +Usage: +$ cobo webhook trigger EVENT_TYPE [--override JSON_STRING] +$ cobo webhook events +$ cobo webhook listen [--events EVENT_LIST] [--forward URL] + +Options for trigger: +- `EVENT_TYPE`: The type of event to trigger (required). +- `--override`: JSON string to override event data. + +Options for listen: +- `--events`: Comma-separated list of event types to listen for. +- `--forward`: URL to forward events to. + +Examples: +```bash +$ cobo webhook trigger wallets.transaction.updated --override '{"amount": 100}' +$ cobo webhook events +$ cobo webhook listen --events wallets.transaction.updated --forward http://example.com/webhook +``` + +This reference covers all the main commands and subcommands available in the +Cobo CLI tool. Each command has various options and arguments that can be used +to customize its behavior. For more detailed information about a specific +command, you can use the --help option with any command or subcommand. diff --git a/v2/cobo-cli/utility-commands/api-documentation.mdx b/v2/cobo-cli/utility-commands/api-documentation.mdx new file mode 100644 index 00000000..6f75cd9d --- /dev/null +++ b/v2/cobo-cli/utility-commands/api-documentation.mdx @@ -0,0 +1,100 @@ +--- +title: API Documentation +--- + +The Cobo CLI provides several commands to help you access and understand the API documentation for Cobo's Wallet-as-a-Service (WaaS) 2.0. This guide will walk you through various ways to retrieve API information directly from the command line. + +## Using the `doc` Command + +The `doc` command allows you to quickly access API reference information for specific endpoints. + +To get information about a specific API endpoint: + +```bash +$ cobo doc /wallets/mpc/vaults +``` + +This will display detailed information about the `/wallets/mpc/vaults` endpoint, including its description, parameters, and response format. + +## Describing API Endpoints with HTTP Methods + +You can use the `-d` or `--describe` flag with the HTTP method commands (`get`, `post`, `put`, `delete`) to get help on specific API endpoints. + +For example, to get information about a GET endpoint: + +```bash +$ cobo get -d /wallets +``` + +This will show you the description, parameters, and other details for the GET request to `/wallets`, which lists all wallets. + +## Getting Help on Specific Parameters + +You can also use the `-d` or `--describe` flag to get help on one or multiple parameters for an API endpoint. This is particularly useful when you need information about specific fields in the request. + +To get help on a single parameter: + +```bash +$ cobo post -d /wallets/mpc/vaults --name +``` + +This will provide detailed information about the `name` parameter for the `/wallets/mpc/vaults` endpoint, which creates a new MPC vault. + +To get help on multiple parameters: + +```bash +$ cobo post -d /wallets/mpc/vaults --name --vault_type +``` + +This will display information about both the `name` and `vault_type` parameters for creating an MPC vault. + +## Updating the OpenAPI Specification + +The Cobo CLI uses an OpenAPI specification to provide accurate and up-to-date information about the API. This specification is automatically updated on a weekly basis to ensure you have access to the most recent API documentation. + +However, if you need to force an update before the next scheduled update, you can use the `doc` command with the `-u` flag: + +```bash +$ cobo doc -u +``` + +When you run this command, the CLI performs the following actions: + +1. It sends a GET request to the Cobo GitHub repository to fetch the latest OpenAPI specification file from: + `https://raw.githubusercontent.com/CoboGlobal/developer-site/master/v2/cobo_waas2_openapi_spec/dev_openapi.yaml` + +2. If the request is successful, it downloads the content of the YAML file. + +3. The CLI then saves this file to your local configuration directory, typically as `openapi.yaml` in the Cobo CLI configuration folder. + +4. If the download and save operations are successful, you'll see a message: "OpenAPI specification file downloaded successfully." + +This process ensures that your local copy of the API specification is immediately updated with the latest version published by Cobo, regardless of when the last automatic update occurred. + + +The automatic weekly update occurs when you run any command that requires the OpenAPI specification. If the spec file is older than one week, the CLI will attempt to update it before proceeding with the command. + + +It's generally not necessary to manually update the specification unless you specifically need the very latest changes before the next automatic update. However, running this command can be useful if you're experiencing unexpected API behaviors or if you know there have been recent changes to the API that you need to access immediately. + + +If there's an error during the manual or automatic update process, such as network issues or permission problems, the CLI will display an error message explaining what went wrong. + + +## Using a Custom API Specification File + +If you have a custom OpenAPI specification file, you can use it with the Cobo CLI. This is useful for testing or working with different versions of the API. + +To use a custom specification file: + +```bash +$ cobo --spec /path/to/custom_spec.yaml get /wallets -d +``` + +Replace `/path/to/custom_spec.yaml` with the actual path to your custom specification file. + + +Using a custom specification file will override the default OpenAPI specification for that command only. It won't affect other commands or future uses of the CLI. + + +By utilizing these commands and options, you can efficiently navigate and understand Cobo's WaaS 2.0 API documentation directly from your command line interface. This integration of documentation with the CLI tool streamlines the development process and helps you quickly find the information you need while working with Cobo's WaaS 2.0 services. diff --git a/v2/cobo-cli/utility-commands/open-browser-shortcuts.mdx b/v2/cobo-cli/utility-commands/open-browser-shortcuts.mdx new file mode 100644 index 00000000..acacac9f --- /dev/null +++ b/v2/cobo-cli/utility-commands/open-browser-shortcuts.mdx @@ -0,0 +1,86 @@ +--- +title: Open Browser Shortcuts +--- + +The Cobo CLI provides a convenient way to quickly open various pages of the Cobo +Portal in your default web browser. This feature helps you navigate to specific +sections of the portal without manually typing URLs. + +## Usage + +To open a specific page, use the `open` command followed by the target page name: + +```bash +$ cobo open +``` + +Where `` is one of the available page shortcuts. + +## Available Shortcuts + +The following shortcuts are available: + +- `portal`: Open the main Cobo Portal page +- `dashboard`: Open the Dashboard page +- `wallets`: Open the Wallets overview page +- `custodial`: Open the Custodial Wallets management page +- `mpc`: Open the MPC Wallets management page +- `scw`: Open the Smart Contract Wallets management page +- `exchange`: Open the Exchange Wallets management page +- `tx`: Open the Transaction page +- `rc`: Open the Risk Control page +- `address`: Open the Address Book page +- `developer`: Open the Developers page +- `apps`: Open the Apps page +- `org`: Open the Organization overview page +- `members`: Open the Organization Members page +- `fee`: Open the Fee Station page +- `roles`: Open the User Roles and Permissions page +- `governance`: Open the Governance Policies page +- `activities`: Open the Activities page +- `guides`: Open the Guides page +- `pricing`: Open the Pricing page +- `approval`: Open the Approval page + +## Examples + +Open the main Cobo Portal page: + +```bash +$ cobo open portal +``` + +Open the MPC Wallets management page: + +```bash +$ cobo open mpc +``` + +Open the Developers page: + +```bash +$ cobo open developer +``` + +## Notes + +- The command will open the specified page in your default web browser. +- The URL opened will correspond to the currently set environment (development, sandbox, or production). +- If an invalid target is provided, the CLI will display an error message. +- Some targets require you to be logged in to the Cobo Portal. If you're not logged in, you'll be redirected to the login page before accessing the requested page. + + +You can use the `-e / --env` option to specify a different environment for the opened URL. For example: + +```bash +$ cobo -e prod open dashboard +``` + +This will open the dashboard in the production environment, regardless of your current CLI environment setting. + + + +Targets such as `dashboard`, `wallets`, `custodial`, `mpc`, `scw`, `exchange`, `tx`, `rc`, `address`, `apps`, `org`, `members`, `fee`, `roles`, `governance`, `activities`, and `approval` require authentication. If you're not logged in, you'll be redirected to the login page first. + + +By using these shortcuts, you can quickly access different sections of the Cobo Portal, streamlining your workflow and saving time navigating through the web interface. diff --git a/v2/cobo-cli/utility-commands/real-time-logs.mdx b/v2/cobo-cli/utility-commands/real-time-logs.mdx new file mode 100644 index 00000000..8f773048 --- /dev/null +++ b/v2/cobo-cli/utility-commands/real-time-logs.mdx @@ -0,0 +1,72 @@ +--- +title: Real-time Logs +--- + +The Cobo CLI provides a powerful feature to tail real-time logs of your API +requests. This is particularly useful for debugging and monitoring your API +usage in real-time. + +## Tailing Logs + +To start tailing logs, use the `logs tail` command: + +```bash +$ cobo logs tail +``` + +This command will start streaming logs in real-time. Each log entry will display +detailed information about the API request, including the request method, +endpoint, status code, and more. + +## Filtering Logs + +You can filter the logs based on various criteria to focus on specific types of requests. The following options are available: + +- `--http-method`: Filter logs by HTTP method (e.g., GET, POST) +- `--request-path`: Filter logs by request path +- `--status-code`: Filter logs by status code +- `--api-key`: Filter logs by API key +- `--ip-address`: Filter logs by IP address + +For example, to tail logs for POST requests only: + +```bash +$ cobo logs tail --http-method POST +``` + +## Limiting the Number of Logs + +By default, the `logs tail` command fetches 3 logs per request. You can adjust this using the `--limit` option: + +```bash +$ cobo logs tail --limit 5 +``` + +This will fetch 5 logs per request. + +## Log Details + +Each log entry provides detailed information about the API request: + +- Log ID +- Timestamp +- HTTP Method +- API Endpoint +- Status Code +- IP Address +- API Key +- Query Parameters +- Request Body +- Response Body + +This comprehensive information helps you understand exactly what's happening with your API requests in real-time. + +## Stopping the Tail + +To stop tailing logs, simply press `Ctrl+C` in your terminal. + + +The `logs tail` command requires appropriate authentication. Make sure you're logged in and have the necessary permissions to access the logs. + + +By using the `logs tail` command, you can gain valuable insights into your API usage, helping you debug issues, monitor activity, and ensure the smooth operation of your Cobo-powered applications. \ No newline at end of file diff --git a/v2/cobo-cli/utility-commands/version-and-updates.mdx b/v2/cobo-cli/utility-commands/version-and-updates.mdx new file mode 100644 index 00000000..c4295510 --- /dev/null +++ b/v2/cobo-cli/utility-commands/version-and-updates.mdx @@ -0,0 +1,81 @@ +--- +title: 'Version and Updates' +--- + +The Cobo CLI provides a simple command to check the current version of the tool. This can be useful for ensuring you're using the latest version and for troubleshooting purposes. + +## Check Current Version + +To display the current version of the Cobo CLI tool, use the following command: + +```bash +$ cobo version +``` + +This command will output the version number of the Cobo CLI tool currently installed on your system. + +Example output: + +```bash +Cobo CLI version: 0.1.0 +``` + + +The version number displayed will correspond to the actual version of the Cobo +CLI tool you have installed. The example above shows version 0.1.0, but your +version may be different. + + +## Updating Cobo CLI + +To ensure you have access to the latest features and bug fixes, it's important +to keep your Cobo CLI tool up to date. The update process depends on how you +initially installed the tool: + +### Updating via pip + +If you installed Cobo CLI using pip, you can update it with the following command: + +```bash +$ pip install --upgrade cobo-cli +``` + +### Updating on macOS (Homebrew) + +If you installed Cobo CLI using Homebrew on macOS, you can update it with these commands: + +```bash +$ brew update +$ brew upgrade cobo/cobo-cli +``` + +After updating, verify the new version: + +```bash +$ cobo version +``` + + +## Best Practices for Updates + +1. **Check for updates regularly**: Before starting a new project or periodically during development, check if there's a new version available. + +2. **Review changelog**: After updating, it's a good idea to review the changelog to understand what's new or changed in the latest version. + + +The Cobo team regularly releases updates to improve functionality, add new +features, and fix any reported issues. Staying up to date ensures you have the +best possible experience with the Cobo CLI tool. + + +## Troubleshooting Version Issues + +If you encounter any issues related to the Cobo CLI version, consider the following steps: + +1. Ensure you're running the latest version of the tool. +2. If problems persist after updating, try uninstalling and reinstalling the Cobo CLI. +3. Check the Cobo documentation or community forums for any known issues related to your specific version. + +By keeping your Cobo CLI tool updated and being aware of its version, you can +ensure smooth operation and take advantage of the latest features and +improvements in your development workflow. \ No newline at end of file diff --git a/v2/cobo-cli/webhooks/listen-and-forward-events.mdx b/v2/cobo-cli/webhooks/listen-and-forward-events.mdx new file mode 100644 index 00000000..c9f14eee --- /dev/null +++ b/v2/cobo-cli/webhooks/listen-and-forward-events.mdx @@ -0,0 +1,70 @@ +--- +title: 'Listen and Forward Events' +--- + +The Cobo CLI provides a powerful feature to listen for webhook events in +real-time and optionally forward them to a specified URL. This functionality is +particularly useful during development and testing of your integration with Cobo +WaaS 2.0. + +## Listening for Webhook Events + +To start listening for webhook events, use the `webhook listen` command: + +```bash +$ cobo webhook listen +``` + +This command establishes a WebSocket connection to the Cobo server and starts streaming all available webhook events. + +### Filtering Events + +You can filter the events you want to listen for by specifying event types: + +```bash +$ cobo webhook listen --events EVENT_TYPE1,EVENT_TYPE2 +``` + +Replace `EVENT_TYPE1,EVENT_TYPE2` with the specific event types you're interested in, separated by commas. + + +To see a list of all available event types, run `cobo webhook events`. + + +## Forwarding Events + +The CLI can also forward received events to a specified URL, which is useful for testing your webhook endpoint: + +```bash +$ cobo webhook listen --forward https://your-endpoint.com/webhook +``` + +This will send a POST request to the specified URL for each event received. + +## Combining Filtering and Forwarding + +You can combine event filtering and forwarding in a single command: + +```bash +$ cobo webhook listen --events EVENT_TYPE1,EVENT_TYPE2 --forward https://your-endpoint.com/webhook +``` + +## Output + +The CLI will print each received event to the console in JSON format. If forwarding is enabled, it will also attempt to send the event to the specified URL and report any errors encountered during forwarding. + +## Stopping the Listener + +To stop listening for events, simply press `Ctrl+C` in your terminal. The CLI will gracefully close the WebSocket connection and terminate the process. + +## Best Practices + +1. **Use in Development**: The `webhook listen` command is primarily intended for use in development and testing environments. For production, set up a proper webhook endpoint in your application. + +2. **Secure Forwarding**: When using the `--forward` option, ensure that your endpoint is properly secured, especially if you're forwarding to a public URL. + +3. **Event Type Familiarity**: Familiarize yourself with the available event types by running `cobo webhook events`. This will help you filter for relevant events and reduce noise in your testing process. + +4. **Error Handling**: Pay attention to any error messages in the CLI output, especially when forwarding events. This can help you identify and resolve issues with your webhook endpoint. + +By leveraging the Cobo CLI's webhook listening and forwarding capabilities, you can streamline your development process and ensure robust handling of Cobo WaaS 2.0 webhook events in your application. diff --git a/v2/cobo-cli/webhooks/trigger-events.mdx b/v2/cobo-cli/webhooks/trigger-events.mdx new file mode 100644 index 00000000..b30d39c2 --- /dev/null +++ b/v2/cobo-cli/webhooks/trigger-events.mdx @@ -0,0 +1,94 @@ +--- +title: 'Trigger Webhook Events' +--- + +The Cobo CLI provides a convenient way to trigger test webhook events, allowing +you to simulate various scenarios and test your webhook integration without +affecting real data. + +## Usage + +To trigger a test webhook event, use the following command: + +```bash +$ cobo webhook trigger [--override ] +``` + +### Parameters + +- ``: The type of webhook event you want to trigger. This is a required parameter. +- `--override `: (Optional) A JSON string to override specific fields in the event payload. + +## Supported Event Types + +The Cobo CLI supports triggering the following webhook event types: + +- `wallets.transaction.created` +- `wallets.transaction.updated` +- `wallets.transaction.failed` +- `wallets.transaction.succeeded` +- `wallets.mpc.tss_request.created` +- `wallets.mpc.tss_request.updated` +- `wallets.mpc.tss_request.failed` +- `wallets.mpc.tss_request.succeeded` + + + To get the most up-to-date list of supported event types, you can use the + `cobo webhook events` command. + + +## Examples + +### Trigger a simple event + +To trigger a `wallets.transaction.created` event with default data: + +```bash +$ cobo webhook trigger wallets.transaction.created +``` + +### Trigger an event with custom data + +To trigger a `wallets.transaction.updated` event with custom data: + +```bash +$ cobo webhook trigger wallets.transaction.updated --override '{"chain_id": "ETH", "amount": "1000000000000000000"}' +``` + +This command will trigger a `wallets.transaction.updated` event with the specified `chain_id` and `amount` values, while using default values for other fields. + +## Response + +After triggering an event, the CLI will display the event details, including: + +- Event ID +- Event Type +- Timestamp +- Event Data + +Example response: + +```json +{ + "event_id": "evt_1234567890abcdef", + "type": "wallets.transaction.created", + "created_timestamp": 1701396866000, + "data": { + "chain_id": "ETH", + "amount": "1000000000000000000", + "status": "Pending" + } +} +``` + +## Best Practices + +1. **Test all event types**: Trigger events for all the webhook types your application is subscribed to, ensuring your system can handle each type correctly. + +2. **Use realistic data**: When overriding event data, try to use realistic values that match your production scenarios. + +3. **Test error handling**: Trigger events with edge case data to ensure your webhook consumer can handle unexpected scenarios gracefully. + +4. **Verify webhook delivery**: After triggering an event, check your webhook endpoint logs to confirm that the event was received and processed correctly. + +By using the Cobo CLI's webhook trigger feature, you can thoroughly test your webhook integration, ensuring that your application is ready to handle real webhook events in a production environment.