diff --git a/antora.yml b/antora.yml index 19c1906..c23c056 100644 --- a/antora.yml +++ b/antora.yml @@ -19,7 +19,7 @@ asciidoc: astra-db: 'Astra DB' product: 'Astra CLI' product-short: 'Astra' - product-version: '0.6' + product-version: '1.0' db-serverless: 'Serverless (Non-Vector)' db-serverless-vector: 'Serverless (Vector)' db-classic: 'Classic' diff --git a/modules/ROOT/pages/administration.adoc b/in-progress/administration.adoc similarity index 99% rename from modules/ROOT/pages/administration.adoc rename to in-progress/administration.adoc index aba8197..8c7bc6b 100644 --- a/modules/ROOT/pages/administration.adoc +++ b/in-progress/administration.adoc @@ -1,5 +1,5 @@ -= Manage your {product-short} organization with the {product} -:navtitle: Manage {product-short} administration +// Writer's note: This page is no longer published but there is still content that should be retained and reformatted for Astra CLI 1.0. += {product-short} administration commands Use the {product} to manage your {product-short} organization. diff --git a/modules/ROOT/pages/astra-streaming-cli.adoc b/in-progress/astra-streaming-cli.adoc similarity index 99% rename from modules/ROOT/pages/astra-streaming-cli.adoc rename to in-progress/astra-streaming-cli.adoc index 7a354be..bbbd236 100644 --- a/modules/ROOT/pages/astra-streaming-cli.adoc +++ b/in-progress/astra-streaming-cli.adoc @@ -1,5 +1,5 @@ -= Manage {astra_stream} with the {product} -:navtitle: Manage {astra_stream} +// Writer's note: This page is no longer published but there is still content that should be retained and reformatted for Astra CLI 1.0. += {astra_stream} commands Use the {product} to manage your {astra_stream} deployments. @@ -727,7 +727,7 @@ OPTIONS The https://pulsar.apache.org/docs/next/administration-pulsar-shell/[Pulsar shell] is an interactive command-line interface tool for managing and interacting with Pulsar clusters. It is designed to allow developers and administrators to execute Pulsar commands interactively or in a script-like fashion, facilitating tasks such as creating topics, producing and consuming messages, managing schemas, and more. -The {product} provides built-in Pulsar shell support by downloading, installing, configuring, and wapping the `pulsar-shell` utility. +The {product} provides built-in Pulsar shell support by downloading, installing, configuring, and wrapping the `pulsar-shell` utility. Use the `astra streaming pulsar-shell` command to start the Pulsar shell in interactive mode: @@ -756,7 +756,7 @@ default(pulsar-aws-useast2.streaming.datastax.com)> ---- ==== -Type `exit` and press kbd:[Return] to exit the Pulsar shell. +Type `exit` and press kbd:[Enter] to exit the Pulsar shell. The first time you use the `astra streaming pulsar-shell` commands, the {product} downloads and installs the `pulsar-shell` utility to the {product} installation directory (`~/.astra/lunastreaming-shell-*`). diff --git a/in-progress/change-data-capture.adoc b/in-progress/change-data-capture.adoc new file mode 100644 index 0000000..0227bfa --- /dev/null +++ b/in-progress/change-data-capture.adoc @@ -0,0 +1,153 @@ += Configure Change Data Capture (CDC) with the {product} +:navtitle: Change Data Capture quickstart + +Change Data Capture (CDC) for {astra_db} automatically captures changes in real time, de-duplicates the changes, and then streams the clean set of changed data into xref:astra-streaming:ROOT:index.adoc[{astra_stream}] where it can be processed by client applications or sent to downstream systems. + +This page provides an end-to-end example that shows you how to use the {product} to enable CDC for an {astra-db} database. + +== Create a database + +Create an {astra_db} database: + +[source,shell] +---- +astra db create cdc_demo_db -r us-east1 -k cdc_demo_keyspace +---- + +.Result +[%collapsible] +==== +[source,console] +---- +Database 'cdc_demo_db' has been created with id 'ce5e563c-3248-4064-b03c-5892433a1347'. It is now active after waiting 422 seconds. +---- +==== + +== Create a streaming tenant + +Create an {astra_stream} tenant in the same region as your database: + +[source,shell] +---- +astra streaming create cdc-demo-tenant -c gcp -r useast1 +---- + +.Result +[%collapsible] +==== +[source,console] +---- +https://api.astra.datastax.com/v2/streaming/tenants/cdc-demo-tenant +[OK] Tenant 'cdc-demo-tenant' has being created. +---- +==== + +== Create a table in your database + +Use `xref:commands:astra-db-cqlsh-exec.adoc[]` to create a table with a primary key column in your database: + +[source,shell] +---- +astra db cqlsh exec cdc_demo_db \ + "CREATE TABLE IF NOT EXISTS cdc_demo_keyspace.cdc_demo_table ( \ + key text PRIMARY KEY, \ + c1 text \ + );" +---- + +.Result +[%collapsible] +==== +[source,console] +---- +[INFO] Cqlsh is starting, please wait for connection establishment... +---- +==== + +Confirm table creation: ++ +[source,shell] +---- +astra db cqlsh exec cdc_demo_db \ + "SELECT * FROM cdc_demo_keyspace.cdc_demo_table" +---- + +.Result +[%collapsible] +==== +[source,console] +---- +[INFO] Cqlsh is starting, please wait for connection establishment... + + key | c1 +-----+---- + +(0 rows) +---- +==== + +== Create a CDC connection + +Use `xref:commands:astra-db-create-cdc.adoc[]` to create a CDC connection between your database table and streaming tenant: + +[source,shell] +---- +astra db create-cdc cdc_demo_db \ + -k cdc_demo_keyspace \ + --table cdc_demo_table \ + --tenant cdc-demo-tenant +---- ++ +//// +// TODO: The command is not working as expected. Must investigate and figure out why it is reporting the following error: [ERROR] INVALID_ARGUMENT: Error Code=422(422) Invalid information provided to create DB: 422 Unprocessable Entity: databaseId, keyspace, tableName, and orgId are mandatory fields +.Result +[%collapsible] +==== +[source,console] +---- + +---- +==== +//// + +Use `xref:commands:astra-db-list-cdcs.adoc[]` to confirm CDC details for the database and tenant: + +[source,shell] +---- +astra db list-cdcs cdc_demo_db +---- + +.Result +[%collapsible] +==== +[source,console] +---- ++-----------------------+-------------------+----------------+----------------+--------------------+----------------+----------------+ +| id | keyspace | table | tenant | cluster | namespace | Status | ++-----------------------+-------------------+----------------+----------------+--------------------+----------------+----------------+ +| 57a3024f-cdcdemotable | cdc_demo_keyspace | cdc_demo_table | cdc-demo-tenant| pulsar-aws-useast1 | astracdc | Running | ++-----------------------+-------------------+----------------+----------------+--------------------+----------------+----------------+ +---- +==== + +[source,shell] +---- +astra streaming list-cdc cdc-demo-tenant +---- + +.Result +[%collapsible] +==== +[source,console] +---- ++--------------------+----------------+----------------+-------------------+----------------+----------------+ +| cluster | namespace | database | keyspace | table | status | ++--------------------+----------------+----------------+-------------------+----------------+----------------+ +| pulsar-aws-useast1 | astracdc | cdc_demo_db | cdc_demo_keyspace | cdc_demo_table | running | ++--------------------+----------------+----------------+-------------------+----------------+----------------+ +---- +==== + +== Connect a sink + +After you enable CDC on your {db-serverless} database, you're ready to xref:astra-streaming:developing:astream-cdc.adoc#connect-a-sink[connect a sink]. diff --git a/in-progress/dsbulk.adoc b/in-progress/dsbulk.adoc new file mode 100644 index 0000000..d88523e --- /dev/null +++ b/in-progress/dsbulk.adoc @@ -0,0 +1,351 @@ += Run DataStax Bulk Loader (DSBulk) commands +:navtitle: DSBulk quickstart + +xref:dsbulk:overview:dsbulk-about.adoc[DataStax Bulk Loader (DSBulk)] is a utility that you can use to load, unload, and count data in your database tables. +The {product} provides embedded DSBulk support by downloading, installing, configuring, and wrapping the `dsbulk` utility. + +The {product} exposes DSBulk functionality through the following commands: + +* `xref:commands:astra-db-dsbulk-load.adoc[]` +* `xref:commands:astra-db-dsbulk-unload.adoc[]` +* `xref:commands:astra-db-dsbulk-count.adoc[]` + +The first time you use one of these commands, the {product} downloads and installs the `dsbulk` utility to the {product} home directory (`xref:ROOT:manage-cli.adoc#file-locations[~/.astra]`). +The {product} also downloads the {scb} for each database you connect to and stores the {scb-short} zip files. + +== Load data + +Use the `xref:commands:astra-db-dsbulk-load.adoc[]` command to load data from a file into a database table: + +[source,shell,subs="+quotes"] +---- +astra db dsbulk load **DB_ID** -k **KEYSPACE_NAME** -t **TABLE_NAME** --url **FILE_LOCATION** +---- + +.Result +[%collapsible] +==== +[source,console] +---- +[INFO] Downloading Dsbulk, please wait... +[INFO] Installing archive, please wait... +[INFO] RUNNING: /Users/USERNAME/.astra/dsbulk-1.11.0/bin/dsbulk load -u token -p AstraCS:FZm... -b /Users/USERNAME/.astra/scb/scb_91b35105-a5aa-4cd5-a93b-900ac58452ba_us-east1.zip -k dsbulk_demo_keyspace -t cities_by_country -logDir ./logs --log.verbosity normal --schema.allowMissingFields true -maxConcurrentQueries AUTO -delim , -url cities.csv -header true -encoding UTF-8 -skipRecords 0 -maxErrors 100 +[INFO] DSBulk is starting please wait ... +Username and password provided but auth provider not specified, inferring PlainTextAuthProvider +A cloud secure connect bundle was provided: ignoring all explicit contact points. +A cloud secure connect bundle was provided and selected operation performs writes: changing default consistency level to LOCAL_QUORUM. +Operation directory: /Users/USERNAME/logs/LOAD_20250123-020734-995267 +Setting executor.maxPerSecond not set when connecting to DataStax Astra: applying a limit of 27,000 ops/second based on the number of coordinators (9). +If your Astra database has higher limits, please define executor.maxPerSecond explicitly. + total | failed | rows/s | p50ms | p99ms | p999ms | batches +148,266 | 0 | 19,588 | 240.82 | 771.75 | 964.69 | 30.72 +Operation LOAD_20250123-020734-995267 completed successfully in 7 seconds. +Checkpoints for the current operation were written to checkpoint.csv. +To resume the current operation, re-run it with the same settings, and add the following command line flag: +--dsbulk.log.checkpoint.file=/Users/USERNAME/logs/LOAD_20250123-020734-995267/checkpoint.csv +---- +==== + +[TIP] +====== +You can use the `xref:commands:astra-db-cqlsh-exec.adoc[]` command to check that the data imported successfully: + +[source,shell,subs="+quotes"] +---- +astra db cqlsh exec **DB_ID** "SELECT * FROM **KEYSPACE_NAME**.**TABLE_NAME** LIMIT 20;" +---- + +.Result +[%collapsible] +==== +[source,console] +---- +[INFO] Cqlsh is starting, please wait for connection establishment... + + country_name | name | country_code | country_id | id | latitude | longitude | state_code | state_id | state_name | wikidataid +--------------+---------------------+--------------+------------+------+----------+-----------+------------+----------+---------------------+------------ + Bangladesh | Azimpur | BD | 19 | 8454 | 23.7298 | 90.3854 | 13 | 771 | Dhaka District | null + Bangladesh | Badarganj | BD | 19 | 8455 | 25.67419 | 89.05377 | 55 | 759 | Rangpur District | null + Bangladesh | Bagerhat | BD | 19 | 8456 | 22.4 | 89.75 | 27 | 811 | Khulna District | null + Bangladesh | Bandarban | BD | 19 | 8457 | 22 | 92.33333 | B | 803 | Chittagong Division | null + Bangladesh | Baniachang | BD | 19 | 8458 | 24.51863 | 91.35787 | 60 | 767 | Sylhet District | null + Bangladesh | Barguna | BD | 19 | 8459 | 22.13333 | 90.13333 | 06 | 818 | Barisal District | null + Bangladesh | Barisal | BD | 19 | 8460 | 22.8 | 90.5 | 06 | 818 | Barisal District | null + Bangladesh | Bera | BD | 19 | 8462 | 24.07821 | 89.63262 | 54 | 813 | Rajshahi District | null + Bangladesh | Bhairab Bāzār | BD | 19 | 8463 | 24.0524 | 90.9764 | 13 | 771 | Dhaka District | null + Bangladesh | Bherāmāra | BD | 19 | 8464 | 24.02452 | 88.99234 | 27 | 811 | Khulna District | null + Bangladesh | Bhola | BD | 19 | 8465 | 22.36667 | 90.81667 | 06 | 818 | Barisal District | null + Bangladesh | Bhāndāria | BD | 19 | 8466 | 22.48898 | 90.06273 | 06 | 818 | Barisal District | null + Bangladesh | Bhātpāra Abhaynagar | BD | 19 | 8467 | 23.01472 | 89.43936 | 27 | 811 | Khulna District | null + Bangladesh | Bibir Hat | BD | 19 | 8468 | 22.68347 | 91.79058 | B | 803 | Chittagong Division | null + Bangladesh | Bogra | BD | 19 | 8469 | 24.78333 | 89.35 | 54 | 813 | Rajshahi District | null + Bangladesh | Brahmanbaria | BD | 19 | 8470 | 23.98333 | 91.16667 | B | 803 | Chittagong Division | null + Bangladesh | Burhānuddin | BD | 19 | 8471 | 22.49518 | 90.72391 | 06 | 818 | Barisal District | null + Bangladesh | Bājitpur | BD | 19 | 8472 | 24.21623 | 90.95002 | 13 | 771 | Dhaka District | null + Bangladesh | Chandpur | BD | 19 | 8474 | 23.25 | 90.83333 | B | 803 | Chittagong Division | null + Bangladesh | Chapai Nababganj | BD | 19 | 8475 | 24.68333 | 88.25 | 54 | 813 | Rajshahi District | null + +(20 rows) +---- +==== +====== + +== Unload data + +Use the `xref:commands:astra-db-dsbulk-unload.adoc[]` command to unload database table rows into a file: + +[source,shell,subs="+quotes"] +---- +astra db dsbulk unload **DB_ID** -k **KEYSPACE_NAME** -t **TABLE_NAME** --url **FILE_LOCATION** +---- + +.Result +[%collapsible] +==== +[source,console] +---- +[INFO] RUNNING: /Users/USERNAME/.astra/dsbulk-1.11.0/bin/dsbulk unload -u token -p AstraCS:FZm... -b /Users/USERNAME/.astra/scb/scb_91b35105-a5aa-4cd5-a93b-900ac58452ba_us-east1.zip -k dsbulk_demo_keyspace -t cities_by_country -logDir ./logs --log.verbosity normal --schema.allowMissingFields true -maxConcurrentQueries AUTO -delim , -url unloaded_data -header true -encoding UTF-8 -skipRecords 0 -maxErrors 100 +[INFO] DSBulk is starting please wait ... +Username and password provided but auth provider not specified, inferring PlainTextAuthProvider +A cloud secure connect bundle was provided: ignoring all explicit contact points. +Operation directory: /Users/USERNAME/logs/UNLOAD_20250123-021231-557959 + total | failed | rows/s | p50ms | p99ms | p999ms +134,574 | 0 | 29,767 | 281.25 | 591.40 | 591.40 +Operation UNLOAD_20250123-021231-557959 completed successfully in 4 seconds. +Checkpoints for the current operation were written to checkpoint.csv. +To resume the current operation, re-run it with the same settings, and add the following command line flag: +--dsbulk.log.checkpoint.file=/Users/USERNAME/logs/UNLOAD_20250123-021231-557959/checkpoint.csv +---- +==== + +== Count data + +Use the `xref:commands:astra-db-dsbulk-count.adoc[]` command to get information about loaded data: + +[source,shell,subs="+quotes"] +---- +astra db dsbulk count **DB_ID** -k **KEYSPACE_NAME** -t **TABLE_NAME** +---- + +.Result +[%collapsible] +==== +[source,console] +---- +[INFO] RUNNING: /Users/USERNAME/.astra/dsbulk-1.11.0/bin/dsbulk count -u token -p AstraCS:FZm... -b /Users/USERNAME/.astra/scb/scb_91b35105-a5aa-4cd5-a93b-900ac58452ba_us-east1.zip -k dsbulk_demo_keyspace -t cities_by_country -logDir ./logs --log.verbosity normal --schema.allowMissingFields true -maxConcurrentQueries AUTO +[INFO] DSBulk is starting please wait ... +Username and password provided but auth provider not specified, inferring PlainTextAuthProvider +A cloud secure connect bundle was provided: ignoring all explicit contact points. +Operation directory: /Users/USERNAME/logs/COUNT_20250123-021120-127216 + total | failed | rows/s | p50ms | p99ms | p999ms +134,574 | 0 | 65,674 | 213.18 | 329.25 | 329.25 +Operation COUNT_20250123-021120-127216 completed successfully in 1 second. +Checkpoints for the current operation were written to checkpoint.csv. +To resume the current operation, re-run it with the same settings, and add the following command line flag: +--dsbulk.log.checkpoint.file=/Users/USERNAME/logs/COUNT_20250123-021120-127216/checkpoint.csv +134574 +---- +==== + +== Complete DSBulk example + +The following end-to-end example shows how to use the {product}'s built-in DSBulk support to load data into a database, get information about the data, and unload the data into CSV files: + +. Create an {astra_db} {db-serverless} database: ++ +[source,shell] +---- +astra db create dsbulk_demo_db -r us-east1 -k dsbulk_demo_keyspace +---- ++ +.Result +[%collapsible] +==== +[source,console] +---- +Database 'dsbulk_demo_db' has been created with id '8b8fea68-404e-4f12-9a79-02079060adfa'. It is now active after waiting 433 seconds. +---- +==== + +. Download the xref:ROOT:attachment$cities.csv[cities.csv] file and move it to the directory where you run {product} commands. ++ +The `cities.csv` dataset contains information about cities around the world: ++ +.cities.csv +[source,csv] +---- +id,name,state_id,state_code,state_name,country_id,country_code,country_name,latitude,longitude,wikiDataId +52,Ashkāsham,3901,BDS,Badakhshan,1,AF,Afghanistan,36.68333000,71.53333000,Q4805192 +68,Fayzabad,3901,BDS,Badakhshan,1,AF,Afghanistan,37.11664000,70.58002000,Q156558 +... +---- + +. Create a table in your database to store your data. ++ +.. Start `cqlsh` in interactive mode: ++ +[source,shell] +---- +astra db cqlsh start dsbulk_demo_db -k dsbulk_demo_keyspace +---- ++ +.Result +[%collapsible] +==== +[source,console] +---- +Connected to cndb at 127.0.0.1:9042. +[cqlsh 6.8.0 | Cassandra 4.0.0.6816 | CQL spec 3.4.5 | Native protocol v4] +Use HELP for help. +token@cqlsh:dsbulk_demo_keyspace> +---- +==== ++ +.. Copy and paste the following CQL statement into the `cqlsh` prompt and press kbd:[Enter]: ++ +[source,cql] +---- +CREATE TABLE cities_by_country ( + country_name text, + name text, + id int, + state_id text, + state_code text, + state_name text, + country_id text, + country_code text, + latitude double, + longitude double, + wikiDataId text, + PRIMARY KEY ((country_name), name) +); +---- ++ +This CQL statement creates a table named `cities_by_country` with the appropriate schema for the `cities.csv` dataset. ++ +.. Type `exit` or `quit;` and press kbd:[Enter] to exit `cqlsh`. + +. Load the data from the `cities.csv` file into the `cities_by_country` table that you just created in your database: ++ +[source,shell] +---- +astra db dsbulk load dsbulk_demo_db -k dsbulk_demo_keyspace -t cities_by_country --url cities.csv +---- ++ +.Result +[%collapsible] +==== +[source,console] +---- +[INFO] RUNNING: /Users/USERNAME/.astra/dsbulk-1.11.0/bin/dsbulk load -u token -p AstraCS:FZm... -b /Users/USERNAME/.astra/scb/scb_91b35105-a5aa-4cd5-a93b-900ac58452ba_us-east1.zip -k dsbulk_demo_keyspace -t cities_by_country -logDir ./logs --log.verbosity normal --schema.allowMissingFields true -maxConcurrentQueries AUTO -delim , -url cities.csv -header true -encoding UTF-8 -skipRecords 0 -maxErrors 100 +[INFO] DSBulk is starting please wait ... +Username and password provided but auth provider not specified, inferring PlainTextAuthProvider +A cloud secure connect bundle was provided: ignoring all explicit contact points. +A cloud secure connect bundle was provided and selected operation performs writes: changing default consistency level to LOCAL_QUORUM. +Operation directory: /Users/USERNAME/logs/LOAD_20250123-020734-995267 +Setting executor.maxPerSecond not set when connecting to DataStax Astra: applying a limit of 27,000 ops/second based on the number of coordinators (9). +If your Astra database has higher limits, please define executor.maxPerSecond explicitly. + total | failed | rows/s | p50ms | p99ms | p999ms | batches +148,266 | 0 | 19,588 | 240.82 | 771.75 | 964.69 | 30.72 +Operation LOAD_20250123-020734-995267 completed successfully in 7 seconds. +Checkpoints for the current operation were written to checkpoint.csv. +To resume the current operation, re-run it with the same settings, and add the following command line flag: +--dsbulk.log.checkpoint.file=/Users/USERNAME/logs/LOAD_20250123-020734-995267/checkpoint.csv +---- +==== + +. Confirm that the data loaded successfully: ++ +[source,shell] +---- +astra db cqlsh exec dsbulk_demo_db "select * from dsbulk_demo_keyspace.cities_by_country LIMIT 20;" +---- ++ +.Result +[%collapsible] +==== +[source,console] +---- +[INFO] Cqlsh is starting, please wait for connection establishment... + + country_name | name | country_code | country_id | id | latitude | longitude | state_code | state_id | state_name | wikidataid +--------------+---------------------+--------------+------------+------+----------+-----------+------------+----------+---------------------+------------ + Bangladesh | Azimpur | BD | 19 | 8454 | 23.7298 | 90.3854 | 13 | 771 | Dhaka District | null + Bangladesh | Badarganj | BD | 19 | 8455 | 25.67419 | 89.05377 | 55 | 759 | Rangpur District | null + Bangladesh | Bagerhat | BD | 19 | 8456 | 22.4 | 89.75 | 27 | 811 | Khulna District | null + Bangladesh | Bandarban | BD | 19 | 8457 | 22 | 92.33333 | B | 803 | Chittagong Division | null + Bangladesh | Baniachang | BD | 19 | 8458 | 24.51863 | 91.35787 | 60 | 767 | Sylhet District | null + Bangladesh | Barguna | BD | 19 | 8459 | 22.13333 | 90.13333 | 06 | 818 | Barisal District | null + Bangladesh | Barisal | BD | 19 | 8460 | 22.8 | 90.5 | 06 | 818 | Barisal District | null + Bangladesh | Bera | BD | 19 | 8462 | 24.07821 | 89.63262 | 54 | 813 | Rajshahi District | null + Bangladesh | Bhairab Bāzār | BD | 19 | 8463 | 24.0524 | 90.9764 | 13 | 771 | Dhaka District | null + Bangladesh | Bherāmāra | BD | 19 | 8464 | 24.02452 | 88.99234 | 27 | 811 | Khulna District | null + Bangladesh | Bhola | BD | 19 | 8465 | 22.36667 | 90.81667 | 06 | 818 | Barisal District | null + Bangladesh | Bhāndāria | BD | 19 | 8466 | 22.48898 | 90.06273 | 06 | 818 | Barisal District | null + Bangladesh | Bhātpāra Abhaynagar | BD | 19 | 8467 | 23.01472 | 89.43936 | 27 | 811 | Khulna District | null + Bangladesh | Bibir Hat | BD | 19 | 8468 | 22.68347 | 91.79058 | B | 803 | Chittagong Division | null + Bangladesh | Bogra | BD | 19 | 8469 | 24.78333 | 89.35 | 54 | 813 | Rajshahi District | null + Bangladesh | Brahmanbaria | BD | 19 | 8470 | 23.98333 | 91.16667 | B | 803 | Chittagong Division | null + Bangladesh | Burhānuddin | BD | 19 | 8471 | 22.49518 | 90.72391 | 06 | 818 | Barisal District | null + Bangladesh | Bājitpur | BD | 19 | 8472 | 24.21623 | 90.95002 | 13 | 771 | Dhaka District | null + Bangladesh | Chandpur | BD | 19 | 8474 | 23.25 | 90.83333 | B | 803 | Chittagong Division | null + Bangladesh | Chapai Nababganj | BD | 19 | 8475 | 24.68333 | 88.25 | 54 | 813 | Rajshahi District | null + +(20 rows) +---- +==== + +. Count the loaded data: ++ +[source,shell] +---- +astra db dsbulk count dsbulk_demo_db -k dsbulk_demo_keyspace -t cities_by_country +---- ++ +.Result +[%collapsible] +==== +[source,console] +---- +[INFO] RUNNING: /Users/USERNAME/.astra/dsbulk-1.11.0/bin/dsbulk count -u token -p AstraCS:FZm... -b /Users/USERNAME/.astra/scb/scb_91b35105-a5aa-4cd5-a93b-900ac58452ba_us-east1.zip -k dsbulk_demo_keyspace -t cities_by_country -logDir ./logs --log.verbosity normal --schema.allowMissingFields true -maxConcurrentQueries AUTO +[INFO] DSBulk is starting please wait ... +Username and password provided but auth provider not specified, inferring PlainTextAuthProvider +A cloud secure connect bundle was provided: ignoring all explicit contact points. +Operation directory: /Users/USERNAME/logs/COUNT_20250123-021120-127216 + total | failed | rows/s | p50ms | p99ms | p999ms +134,574 | 0 | 65,674 | 213.18 | 329.25 | 329.25 +Operation COUNT_20250123-021120-127216 completed successfully in 1 second. +Checkpoints for the current operation were written to checkpoint.csv. +To resume the current operation, re-run it with the same settings, and add the following command line flag: +--dsbulk.log.checkpoint.file=/Users/USERNAME/logs/COUNT_20250123-021120-127216/checkpoint.csv +134574 +---- +==== + +. Unload the data into CSV files: ++ +[source,shell] +---- +astra db dsbulk unload dsbulk_demo_db -k dsbulk_demo_keyspace -t cities_by_country --url unloaded_data +---- ++ +.Result +[%collapsible] +==== +[source,console] +---- +[INFO] RUNNING: /Users/USERNAME/.astra/dsbulk-1.11.0/bin/dsbulk unload -u token -p AstraCS:FZm... -b /Users/USERNAME/.astra/scb/scb_91b35105-a5aa-4cd5-a93b-900ac58452ba_us-east1.zip -k dsbulk_demo_keyspace -t cities_by_country -logDir ./logs --log.verbosity normal --schema.allowMissingFields true -maxConcurrentQueries AUTO -delim , -url unloaded_data -header true -encoding UTF-8 -skipRecords 0 -maxErrors 100 +[INFO] DSBulk is starting please wait ... +Username and password provided but auth provider not specified, inferring PlainTextAuthProvider +A cloud secure connect bundle was provided: ignoring all explicit contact points. +Operation directory: /Users/USERNAME/logs/UNLOAD_20250123-021231-557959 + total | failed | rows/s | p50ms | p99ms | p999ms +134,574 | 0 | 29,767 | 281.25 | 591.40 | 591.40 +Operation UNLOAD_20250123-021231-557959 completed successfully in 4 seconds. +Checkpoints for the current operation were written to checkpoint.csv. +To resume the current operation, re-run it with the same settings, and add the following command line flag: +--dsbulk.log.checkpoint.file=/Users/USERNAME/logs/UNLOAD_20250123-021231-557959/checkpoint.csv +---- +==== ++ +This command unloads row data from the `cities_by_country` table, and stores it as CSV files within a subsirectory names `unloaded_data` in the same directory where you ran the command. diff --git a/modules/ROOT/pages/managing.adoc b/in-progress/managing.adoc similarity index 99% rename from modules/ROOT/pages/managing.adoc rename to in-progress/managing.adoc index d17c7bd..d9246f6 100644 --- a/modules/ROOT/pages/managing.adoc +++ b/in-progress/managing.adoc @@ -1,5 +1,5 @@ -= Manage {astra_db} with the {product} -:navtitle: Manage {astra_db} +// Writer's note: This page is no longer published but there is still content that should be retained and reformatted for Astra CLI 1.0. += {astra_db} commands :embedding-provider-name: NVIDIA :embedding-provider-name-api: nvidia :embedding-provider-model-name-api: NV-Embed-QA @@ -2772,7 +2772,7 @@ OPTIONS == Use cqlsh `cqlsh` is an interface that you can use to issue xref:astra@cql:ROOT:index.adoc[{cass-short} Query Language (CQL)] commands to your database. -The {product} provides built-in `cqlsh` support by downloading, installing, configuring, and wapping the `cqlsh` utility. +The {product} provides built-in `cqlsh` support by downloading, installing, configuring, and wrapping the `cqlsh` utility. This can act as a convenient alternative to installing and configuring a xref:astra-db-serverless:cql:develop-with-cql.adoc#connect-to-the-cql-shell[standalone cqlsh]. To use `cqlsh` commands, you must have a supported version of Python installed on your system. @@ -2802,7 +2802,7 @@ token@cqlsh> ---- ==== -Type `exit` or `quit;` and press kbd:[Return] to exit `cqlsh`. +Type `exit` or `quit;` and press kbd:[Enter] to exit `cqlsh`. The first time you use the `astra db cqlsh` command, the {product} downloads and installs the `cqlsh` utility to the {product} installation directory (`~/.astra/cqlsh-astra`). The {product} also downloads the {scb} for each database you connect to and stores the {scb-short} zip files in the `~/.astra/scb` directory. @@ -3020,7 +3020,7 @@ astra db cqlsh **DATABASE_ID** -e "SOURCE 'sample.cql'" == Use DataStax Bulk Loader The xref:dsbulk:overview:dsbulk-about.adoc[DataStax Bulk Loader (DSBulk)] lets you load, unload, and count data in your database tables. -The {product} provides built-in DSBulk support by downloading, installing, configuring, and wapping the `dsbulk` utility. +The {product} provides built-in DSBulk support by downloading, installing, configuring, and wrapping the `dsbulk` utility. The {product} exposes DSBulk functionality through the `astra db load`, `astra db unload`, and `astra db count` commands. @@ -3517,7 +3517,7 @@ token@cqlsh:dsbulk_demo_keyspace> ---- ==== + -.. Copy and paste the following CQL command into the `cqlsh` prompt and press kbd:[Return]: +.. Copy and paste the following CQL command into the `cqlsh` prompt and press kbd:[Enter]: + [source,cql] ---- @@ -3539,7 +3539,7 @@ CREATE TABLE cities_by_country ( + This command creates a table named `cities_by_country` with the appropriate schema for the `cities.csv` dataset. + -.. Type `exit` or `quit;` and press kbd:[Return] to exit `cqlsh`. +.. Type `exit` or `quit;` and press kbd:[Enter] to exit `cqlsh`. . Load the data from the `cities.csv` file into the `cities_by_country` table that you just created in your database: + diff --git a/in-progress/quickstart-databases.adoc b/in-progress/quickstart-databases.adoc new file mode 100644 index 0000000..dd47d5b --- /dev/null +++ b/in-progress/quickstart-databases.adoc @@ -0,0 +1,296 @@ +// Writer's note: This page contains a selection of content that was deleted from the Astra Serverless docs. We should retain relevant content reformat it for Astra CLI 1.0. += Manage databases with the {product} +:navtitle: Quickstart for databases +:organization-administrator-role: pass:q[xref:astra-db-serverless:administration:rbac.adoc#organization-administrator-role[*Organization Administrator*]] +:database-administrator-role: pass:q[xref:astra-db-serverless:administration:rbac.adoc#database-administrator-role[*Database Administrator*]] + +You can use the {product} to perform administrative operations on your {astra-db} databases and keyspaces. + +[IMPORTANT] +==== +To perform database operations, you need an application token with permission to create and configure databases, such as the {organization-administrator-role} role. + +To work within databases, you need an application token with permission to interact with the target database, such as the {database-administrator-role} role. +==== + +When you xref:ROOT:manage-cli.adoc[connect the {product}], you provide an application token that authorizes you to run the CLI commands. + +== Find available regions + +Get a list of available regions for database creation. + +== Create a database + +You can create {db-serverless-vector} and {db-serverless} databases. + +[NOTE] +==== +If your organization requires that new databases belong to a xref:astra-db-serverless:administration:provisioned-capacity-units.adoc[PCU group], you cannot use the {product} to create databases because it doesn't support PCU group assignment with database creation. +==== + +Create a database: + +[source,console,subs="+quotes"] +---- +astra db create *DB_NAME* --region *REGION* --cloud *CLOUD_PROVIDER* \ +-k *KEYSPACE* --if-not-exist --async +---- + +Parameters: + +[cols="1,1,2"] +|=== +| Name | Type | Summary + +| `db_name` +| `String` +a| The database name. + +Database names must follow these rules: + +include::common:ROOT:partial$database-name-rules.adoc[] + +| `region` +| `String` (OPTIONAL) +a| A valid xref:databases:regions.adoc[cloud provider region], depending on your xref:administration:subscription-plans.adoc[subscription plan] and the database type. + +include::astra-db-serverless:databases:partial$get-regions-endpoint.adoc[] + +| `cloud` +| `String` (OPTIONAL) +| The cloud provider (`gcp,azure,aws`) to use for the database. + +| `keyspace` +| `String` (OPTIONAL) +a| The name of the database's initial keyspace. +If omitted, the default is `default_keyspace`. + +| `--if-not-exists` +| `flag` (OPTIONAL) +| If provided, this makes the operation idempotent. +Check for an existing database with the same configuration. + +| `--async` +| `flag` (OPTIONAL) +| By default, the operation is synchronous and waits for the database to become active. +Include this option to make the operation asynchronous. + +|=== + +[IMPORTANT] +==== +By default, the command waits until the database is created and ready to use. + +You can set `--async` to skip waiting while the database activates. +However, you cannot perform operations on the new database before it is active. + +To learn more, run `astra help db create`. +==== + +== Find a database + +Get information about one database. + +Get database metadata by database ID: + +[source,console,subs="+quotes"] +---- +astra db describe *DB_ID* +---- + +Parameters: + +[cols="1,1,2"] +|=== +| Name | Type | Summary + +| `DB_ID` +| `String` +| The ID of the target database. +See xref:databases:create-database.adoc#get-db-id[Get your database ID]. + +You can also get metadata by providing the database name, but this doesn't guarantee uniqueness. +|=== + +.Result +[%collapsible] +==== +[source,console] +---- ++------------------+-----------------------------------------+ +| Attribute | Value | ++------------------+-----------------------------------------+ +| Name | astra_db_client | +| id | 4391daae-016c-49e3-8d0a-b4633a86082c | +| Cloud | GCP | +| Regions | us-east1 | +| Status | ACTIVE | +| Vector | Enabled | +| Default Keyspace | default_keyspace | +| Creation Time | 2024-02-24T01:20:03Z | +| | | +| Keyspaces | [0] default_keyspace | +| | | +| | | +| Regions | [0] us-east1 | +| | | ++------------------+-----------------------------------------+ +---- +==== + +=== Find all databases + +Retrieve the listing of all databases. + +List all of your databases: + +[source,console] +---- +astra db list +---- + +.Result +[%collapsible] +==== +[source,console,subs="+quotes"] +---- ++---------------------+--------------+-----------+-------+---+-----------+ +| Name | id | Regions | Cloud | V | Status | ++---------------------+--------------+-----------+-------+---+-----------+ +| astra_db_client | *DB_ID* | us-east1 | gcp | ■ | ACTIVE | ++---------------------+--------------+-----------+-------+---+-----------+ +---- +//ID truncated to prevent bad wrapping. +==== + +== Drop a database + +include::common:ROOT:partial$terminate-db-warn.adoc[] + +Delete a database and erase all data stored in it. + +Delete a database by ID: + +[source,console,subs="+quotes"] +---- +astra db delete *DB_ID* +---- + +Parameters: + +[cols="1,1,2"] +|=== +| Name | Type | Summary + +| `DB_ID` +| `UUID` +| The ID of the database to delete. +See xref:databases:create-database.adoc#get-db-id[Get your database ID]. + +You can also delete a database by name. +However, {company} recommends using the ID to ensure the correct database is deleted. +|=== + +== Create a keyspace + +{db-serverless-vector} databases have an initial keyspace named `default_keyspace`. +You can override the initial keyspace name when you create the database, if desired. + +You can create more keyspaces as needed, such as for better application structure. + +Create a keyspace in a database: + +[source,console,subs="+quotes"] +---- +astra db create-keyspace *DB_ID* -k *KEYSPACE_NAME* +---- + +Parameters: + +[cols="1,1,2"] +|=== +| Name | Type | Summary + +| `DB_ID` +| `String` +| The ID of the database where you want to create the keyspace. +The database must already exist. +See xref:databases:create-database.adoc#get-db-id[Get your database ID]. + +| `KEYSPACE_NAME` +| `String` +a| The unique name for the keyspace. + +Keyspace names must follow these rules: + +include::common:ROOT:partial$keyspace-name-rules.adoc[] +|=== + +== List keyspaces + +Get a list of the keyspaces in a database. + +List keyspaces in a database: + +[source,console,subs="+quotes"] +---- +astra db list-keyspaces *DB_ID* +---- + +Parameters: + +[cols="1,1,2"] +|=== +| Name | Type | Summary + +| `DB_ID` +| `String` +| The ID of the database from which to get the keyspaces. +See xref:databases:create-database.adoc#get-db-id[Get your database ID]. +|=== + +.Result +[%collapsible] +==== +[source,console] +---- ++----------------------------+ +| Name | ++----------------------------+ +| default_keyspace (default) | +| keyspace2 | ++----------------------------+ +---- +==== + +== Drop a keyspace + +Delete a keyspace in a database and erase all data stored in that keyspace. + +Delete a keyspace: + +[source,console,subs="+quotes"] +---- +astra db delete-keyspace *DB_ID* -k *KEYSPACE_NAME* +---- + +Parameters: + +[cols="1,1,2"] +|=== +| Name | Type | Summary + +| `DB_ID` +| `String` +| The ID of the database where you want to delete a keyspace. +See xref:databases:create-database.adoc#get-db-id[Get your database ID]. + +| `KEYSPACE_NAME` +| `String` +| The name of the keyspace to delete. +|=== + +== Find embedding providers + +Get information about embedding providers for xref:databases:embedding-generation.adoc[{astra-db} vectorize], including supported providers, models, dimensions, and other configuration parameters. + diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 6b64342..e42a432 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -1,7 +1,17 @@ -* xref:installation.adoc[] -* xref:getting-started.adoc[] -* xref:managing.adoc[] -* xref:astra-streaming-cli.adoc[] -* xref:administration.adoc[] -* https://github.com/datastax/astra-cli[GitHub repo] -* https://github.com/datastax/astra-cli/releases[Release notes] \ No newline at end of file +.Get Started +* xref:install.adoc[] +* xref:manage-cli.adoc[] +* xref:upgrade.adoc[] +* xref:uninstall.adoc[] + +.Quickstarts +* xref:quickstarts:cqlsh.adoc[] + +include::ROOT:partial$partial-nav.adoc[] + +.Release notes +* https://github.com/datastax/astra-cli?tab=readme-ov-file#whats-changed[Release notes] + +//- + +* https://github.com/datastax/astra-cli[GitHub repository] diff --git a/modules/ROOT/pages/getting-started.adoc b/modules/ROOT/pages/getting-started.adoc deleted file mode 100644 index ffb35c7..0000000 --- a/modules/ROOT/pages/getting-started.adoc +++ /dev/null @@ -1,676 +0,0 @@ -= Get started with the {product} -:navtitle: Get started - -Initialize the {product} and run your first commands. - -== Prerequisites - -To configure the {product}: - -* xref:ROOT:installation.adoc[Install the {product}]. - -* You must have an active {astra-url}[{product-short} account^]. - -* [[get-credentials]]You must have an xref:astra-db-serverless:administration:manage-application-tokens.adoc[application token] that is assigned a _role_ with adequate _permissions_ to perform the tasks you'd like to accomplish with the {product}. - -** *Non-production organizations*: If your {product-short} organization has no databases or streaming tenants that handle sensitive information, you can grant your application token the `Organization Administrator` role to try out all of the {product} features. - -** *Production organizations*: If you're using {product-short} in production, {company} recommends that you use a xref:astra-db-serverless:administration:manage-database-access.adoc#custom-roles[custom role] to grant your application token the bare minimum xref:astra-db-serverless:administration:manage-database-access.adoc#about-permissions[permissions] required to perform the required tasks with the {product}. - -* If you plan to manage an {astra_db} database that has restricted public access, then you must xref:astra-db-serverless:administration:manage-database-ip-access-list.adoc#add-ip-access-list-entries[add your IP address to the database's access list]. - -[#initialize] -== Initialize the {product} - -After installation, initialize the {product} and connect it to an existing {product-short} account. - -. Use the `astra setup` command to initialize the {product} with your xref:astra-db-serverless:administration:manage-application-tokens.adoc[application token]: -+ -[source,bash,subs="+quotes"] ----- -astra setup --token *APPLICATION_TOKEN* ----- -+ -Replace `*APPLICATION_TOKEN*` with your application token. -The token format is `AstraCS:` followed by a unique token string. -+ -.Result -[%collapsible] -==== -[source,console] ----- -[OK] Configuration has been saved. -[OK] Setup completed. -[INFO] Enter 'astra help' to list available commands. ----- -==== - -. List the {product} configuration to confirm that your token is in use: -+ -[source,bash] ----- -astra config list ----- -+ -.Result -[%collapsible] -==== -[source,console] ----- -+--------------------------------+ -| configuration | -+--------------------------------+ -| alex@altostrat.com (in use) | -+--------------------------------+ ----- -==== - -The {product} is initialized and your application token is set as the default configuration. -The {product} stores configurations and their associated application tokens in the `~/.astrarc` file. -To create additional configurations, see <>. - -[IMPORTANT] -==== -Application tokens are stored in plain text in the `~/.astrarc` file. -Your application tokens are like passwords, therefore you should take precautions to secure the configuration file. -==== - -== Print help information - -Use `astra help` to print general {product} help information: - -[source,bash] ----- -astra help ----- - -.Result -[%collapsible] -==== -[source,console] ----- -usage: astra [ ] - -Commands are: - ? Display this help version - help Display help information - login Authenticate against Astra. - setup Initialize configuration file - config Manage configuration file - db Manage databases - org Display Organization Info - role Manage roles - streaming Manage Streaming tenants - token Manage tokens - user Manage users - -See 'astra help ' for more information on a specific command. ----- -==== - -Append a command name to print help information about an individual command. -For example: - -[source,bash] ----- -astra help db ----- - -.Result -[%collapsible] -==== -[source,console] ----- -NAME - astra db - Manage databases - -SYNOPSIS - astra db { count | cqlsh | create | create-cdc | create-collection | - create-dotenv | create-keyspace | create-region | delete | - delete-cdc | delete-collection | delete-keyspace | - delete-region | describe | download-scb | get | - get-endpoint-api | get-endpoint-playground | - get-endpoint-swagger | list* | list-cdc | list-clouds | - list-collections | list-keyspaces | list-regions | - list-regions-classic | list-regions-serverless | - list-regions-vector | load | resume | status | unload } [--] - [ --token ] [ --no-color ] [ {-v | --verbose} ] - [ {-conf | --config} ] - [ {-cf | --config-file} ] [ --env ] - [ {-o | --output} ] [cmd-options] - - Where command-specific options [cmd-options] are: - count: [ {-k | --keyspace} ] [ -encoding ] [ {-t | --table} ] - [ {-query | --schema.query} ] [ --dsbulk-config ] - [ -maxConcurrentQueries ] [ -logDir ] - cqlsh: [ --debug ] [ {-f | --file} ] [ {-k | --keyspace} ] - [ --version ] [ --connect-timeout ] [ {-e | --execute} ] - [ --request-timeout ] [ --encoding ] - create: [ {-c | --cloud} ] [ {-k | --keyspace} ] - [ --vector ] [ --timeout ] [ {-r | --region} ] - [ {--if-not-exist | --if-not-exists} ] [ --async ] [ --tier ] - [ --capacity-units ] - create-cdc: [ {-k | --keyspace} ] [ --tenant ] - [ -p, --partition ] [ --table
] - create-collection: [ {-m | --metric} ] {-c | --collection} - [ {-d | --dimension} ] - create-dotenv: [ {-k | --keyspace} ] [ {-d | --directory} ] - [ {-r | --region} ] - create-keyspace: {-k | --keyspace} [ --if-not-exist ] [ --wait ] - create-region: [ {-c | --cloud} ] [ --timeout ] - {-r | --region} [ --wait ] [ {-t | --tier} ] - [ --async ] [ --if-not-exist ] - delete: [ --async ] [ --timeout ] [ --wait ] - delete-cdc: [ {-k | --keyspace} ] [ -id ] [ --tenant ] - [ --table
] - delete-collection: {-c | --collection} - delete-keyspace: {-k | --keyspace} - delete-region: [ --async ] [ --timeout ] {-r | --region} - [ --wait ] - describe: [ {-k | --key} ] - download-scb: [ {-f | --output-file} ] [ {-r | --region} ] - get: [ {-k | --key} ] - get-endpoint-api: [ {-r | --region} ] - get-endpoint-playground: [ {-r | --region} ] - get-endpoint-swagger: [ {-r | --region} ] - list: [ --vector ] - list-cdc: - list-clouds: - list-collections: - list-keyspaces: - list-regions: - list-regions-classic: [ {-c | --cloud} ] [ {-f | --filter} ] - list-regions-serverless: [ {-c | --cloud} ] [ {-f | --filter} ] - list-regions-vector: [ {-c | --cloud} ] [ {-f | --filter} ] - load: [ {-k | --keyspace} ] [ -maxErrors ] [ -encoding ] - [ {-t | --table}
] [ {-query | --schema.query} ] - [ -skipRecords ] [ --schema.allowMissingFields ] - -url [ --dsbulk-config ] [ -dryRun ] - [ -header
] [ -delim ] [ -maxConcurrentQueries ] - [ -logDir ] [ {-m | --schema.mapping} ] - resume: [ --async ] [ --timeout ] [ --wait ] - status: - unload: [ {-k | --keyspace} ] [ -maxErrors ] - [ -encoding ] [ {-t | --table}
] [ {-query | --schema.query} ] - [ -skipRecords ] [ -url ] [ --dsbulk-config ] - [ -header
] [ -delim ] [ -maxConcurrentQueries ] - [ -logDir ] [ {-m | --schema.mapping} ] - - Where command-specific arguments are: - count: - cqlsh: - create: - create-cdc: - create-collection: - create-dotenv: - create-keyspace: - create-region: - delete: - delete-cdc: - delete-collection: - delete-keyspace: - delete-region: - describe: - download-scb: - get: - get-endpoint-api: - get-endpoint-playground: - get-endpoint-swagger: - list: - list-cdc: - list-clouds: - list-collections: - list-keyspaces: - list-regions: - list-regions-classic: - list-regions-serverless: - list-regions-vector: - load: - resume: - status: - unload: - - Where * indicates the default command(s) - See 'astra help db ' for more information on a specific command. ----- -==== - -Append a subcommand for further specificity: - -[source,bash] ----- -astra help db list ----- - -.Result -[%collapsible] -==== -[source,console] ----- -NAME - astra db list - Display the list of Databases in an organization - -SYNOPSIS - astra db list [ {-cf | --config-file} ] - [ {-conf | --config} ] [ --env ] - [ --no-color ] [ {-o | --output} ] - [ --token ] [ {-v | --verbose} ] [ --vector ] - -OPTIONS - -cf , --config-file - Configuration file (default = ~/.astrarc) - - -conf , --config - Section in configuration file (default = ~/.astrarc) - - --env - Astra Environment to use - - --no-color - Remove all colors in output - - -o , --output - Output format, valid values are: human,json,csv - - --token - Key to use authenticate each call. - - -v, --verbose - Verbose mode with log in console - - --vector - Create a database with vector search enabled ----- -==== - -== Set up auto-completion - -The {product} provides Bash auto-completion for `bash` and `zsh` shells. - -To use auto-completion, type the `astra` command and then press kbd:[Tab] twice to get a list of available options. - -[source,bash,subs="macros"] ----- -astra kbd:[Tab] kbd:[Tab] ----- - -.Result -[%collapsible%open] -==== -[source,console] ----- - --no-color config db help role setup shell user ----- -==== - -[#manage-configuration] -== Manage the {product} configuration - -When you run the `astra setup` command during <>, the {product} stores your application token as the default configuration in the `~/.astrarc` configuration file. - -You can create additional configurations, each with their own application token, to make it easier to manage different types of resources across one or more organizations. - -=== Get and set configurations - -. Use `astra config list` to list all current configurations: -+ -[source,bash] ----- -astra config list ----- -+ -.Result -[%collapsible] -==== -[source,console] -+----------------------------+ -| configuration | -+----------------------------+ -| Organization 1 (in use) | -| Organization 2 | -+----------------------------+ -==== - -. Use `astra config create` to create a new configuration: -+ -[source,bash,subs="+quotes"] ----- -astra config create "**CONFIG_NAME**" --token **APPLICATION_TOKEN** ----- -+ -.Result -[%collapsible] -==== -[source,console] ----- -[OK] Configuration has been saved. ----- -==== - -. Use `astra config use` to change the default configuration that {product} uses when executing commands: -+ -[source,bash,subs="+quotes"] ----- -astra config use "**CONFIG_NAME**" ----- -+ -.Result -[%collapsible] -==== -[source,console,subs="+quotes"] ----- -[OK] Section '**CONFIG_NAME**' is set as default. ----- -==== - -. Optional: Rerun `astra config list` to verify that the new default configuration is set. - -=== Set the configuration for a single run - -Every {product} command supports the `--config` option. -This option lets you use a different configuration when running a command without changing the default configuration. -For example: - -[source,bash,subs="+quotes"] ----- -astra user list --config "**CONFIG_NAME**" ----- - -Alternatively, you can use the `--token` option to supply an application token when running a command. -This option lets you use a different application token without having to create a new configuration. -For example: - -[source,bash,subs="+quotes"] ----- -astra user list --token "**APPLICATION_TOKEN**" ----- - -=== Delete a configuration - -Use `astra config delete` to delete a configuration: - -[source,bash,subs="+quotes"] ----- -astra config delete "**CONFIG_NAME**" ----- - -.Result -[%collapsible] -==== -[source,console,subs="+quotes"] ----- -[OK] Section '**CONFIG_NAME**' has been deleted. ----- -==== - -[IMPORTANT] -==== -If you delete the default configuration, the {product} _doesn't_ automatically select a new default configuration. -Use the `astra config use` command to select a new default configuration. -==== - -=== `config` options - -The following options are available for the `astra config` command: - -[source,console] ----- -NAME - astra config - Manage configuration file - -SYNOPSIS - astra config { create | delete | describe | get | list* | use } [--] - [ {-cf | --config-file} ] [ --no-color ] - [ {-v | --verbose} ] [ {-o | --output} ] [cmd-options] - - - Where command-specific options [cmd-options] are: - create: [ {-e | --env} ] [ {-t | --token} ] - delete: - describe: [ {-k | --key} ] - get: [ {-k | --key} ] - list: - use: - - Where command-specific arguments are: - create: [ ] - delete: - describe: - get: - list: - use: - - Where * indicates the default command(s) - See 'astra help config ' for more information on a specific command. ----- - -See the following sections for `config` subcommand options: - -.Expand to see all `config create` options -[%collapsible] -==== -[source,console] ----- -NAME - astra config create - Create a new section in configuration - -SYNOPSIS - astra config create [ {-cf | --config-file} ] - [ {-e | --env} ] [ --no-color ] - [ {-o | --output} ] [ {-t | --token} ] - [ {-v | --verbose} ] [--] [ ] - -OPTIONS - -cf , --config-file - Configuration file (default = ~/.astrarc) - - -e , --env - Environment to use for this section. - - --no-color - Remove all colors in output - - -o , --output - Output format, valid values are: human,json,csv - - -t , --token - Key to use authenticate each call. - - -v, --verbose - Verbose mode with log in console - - -- - This option can be used to separate command-line options from the - list of arguments (useful when arguments might be mistaken for - command-line options) - - - Section in configuration file to as as default. ----- -==== - -.Expand to see all `config delete` options -[%collapsible] -==== -[source,console] ----- -NAME - astra config delete - Delete section in configuration - -SYNOPSIS - astra config delete [ {-cf | --config-file} ] - [ --no-color ] [ {-o | --output} ] - [ {-v | --verbose} ] [--] - -OPTIONS - -cf , --config-file - Configuration file (default = ~/.astrarc) - - --no-color - Remove all colors in output - - -o , --output - Output format, valid values are: human,json,csv - - -v, --verbose - Verbose mode with log in console - - -- - This option can be used to separate command-line options from the - list of arguments (useful when arguments might be mistaken for - command-line options) - - - Section in configuration file to as as default. ----- -==== - -.Expand to see all `config describe` options -[%collapsible] -==== -[source,console] ----- -NAME - astra config describe - Show details for a configuration. - -SYNOPSIS - astra config describe [ {-cf | --config-file} ] - [ {-k | --key} ] [ --no-color ] - [ {-o | --output} ] [ {-v | --verbose} ] [--] - - -OPTIONS - -cf , --config-file - Configuration file (default = ~/.astrarc) - - -k , --key - If provided return only value for a key. - - --no-color - Remove all colors in output - - -o , --output - Output format, valid values are: human,json,csv - - -v, --verbose - Verbose mode with log in console - - -- - This option can be used to separate command-line options from the - list of arguments (useful when arguments might be mistaken for - command-line options) - - - Section in configuration file to as as default. ----- -==== - -.Expand to see all `config get` options -[%collapsible] -==== -[source,console] ----- -NAME - astra config get - Show details for a configuration. - -SYNOPSIS - astra config get [ {-cf | --config-file} ] - [ {-k | --key} ] [ --no-color ] - [ {-o | --output} ] [ {-v | --verbose} ] [--] - - -OPTIONS - -cf , --config-file - Configuration file (default = ~/.astrarc) - - -k , --key - If provided return only value for a key. - - --no-color - Remove all colors in output - - -o , --output - Output format, valid values are: human,json,csv - - -v, --verbose - Verbose mode with log in console - - -- - This option can be used to separate command-line options from the - list of arguments (useful when arguments might be mistaken for - command-line options) - - - Section in configuration file to as as default. ----- -==== - -.Expand to see all `config list` options -[%collapsible] -==== -[source,console] ----- -NAME - astra config list - Show the list of available configurations. - -SYNOPSIS - astra config list [ {-cf | --config-file} ] - [ --no-color ] [ {-o | --output} ] - [ {-v | --verbose} ] - -OPTIONS - -cf , --config-file - Configuration file (default = ~/.astrarc) - - --no-color - Remove all colors in output - - -o , --output - Output format, valid values are: human,json,csv - - -v, --verbose - Verbose mode with log in console ----- -==== - -.Expand to see all `config use` options -[%collapsible] -==== -[source,console] ----- -NAME - astra config use - Make a section the one used by default - -SYNOPSIS - astra config use [ {-cf | --config-file} ] [ --no-color ] - [ {-o | --output} ] [ {-v | --verbose} ] [--] - - -OPTIONS - -cf , --config-file - Configuration file (default = ~/.astrarc) - - --no-color - Remove all colors in output - - -o , --output - Output format, valid values are: human,json,csv - - -v, --verbose - Verbose mode with log in console - - -- - This option can be used to separate command-line options from the - list of arguments (useful when arguments might be mistaken for - command-line options) - - - Section in configuration file to as as default. ----- -==== - -== Next steps - -* xref:ROOT:managing.adoc[] -* xref:ROOT:astra-streaming-cli.adoc[] -* xref:ROOT:administration.adoc[] \ No newline at end of file diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc index 121220d..5f2187b 100644 --- a/modules/ROOT/pages/index.adoc +++ b/modules/ROOT/pages/index.adoc @@ -1,64 +1,50 @@ = {product} :page-layout: landing -The {product} is a free utility that you can use to create and manage {product-short} resources. -You can use the {product} to perform common platform tasks for {astra_db} and {astra_stream} from the command line or with automation to control your {product-short} resources at scale. +A fast, reliable command-line tool for working with {company} {product-short}. -To make it even easier to integrate {product-short} into your applications and workflows, the {product} provides seamless integration with the following external tools: - -* DSBulk -* cqlsh -* pulshar-shell -* Useful shortcuts like dotenv file generation +The {product} gives you full control of your {product-short} resources directly from your terminal. +It's designed for developers and operators who prefer automation, scripting, and repeatable workflows over clicking through the {astra-ui} or interfacing directly with the APIs. [.[&>h2]:!hidden] == {empty} [subs="macros,attributes"] ++++ -
-
- - svg:common:ROOT:icons/datastax/create-db-now.svg[role="mx-auto max-w-xs md:mx-0 lg:max-w-none"] +
+
-

Get started

+

Get started

- - -
- xref:installation.adoc[] -
+

Ready to bring {product-short} to the command line? Install the CLI and learn how to connect and start managing your {product-short} resources in minutes.

-
- xref:getting-started.adoc[] +
+ xref:ROOT:install.adoc[Install the {product},role="btn btn-primary btn-solid"] + xref:commands:astra-setup.adoc[Command reference,role="btn btn-neutral btn-outlined"]
-
- - svg:common:ROOT:icons/datastax/cloud-db.svg[role="mx-auto max-w-xs md:mx-0 lg:max-w-none"] - -

Manage {astra_db}

- - - -
- xref:managing.adoc[] -
+ -
+[source,bash,subs="+quotes",role="nolang absolute bottom-1/2 translate-y-1/2 right-0 w-full inverse-theme [&_.source-toolbox]:hidden"] +---- +# Set up connection profiles +astra setup - svg:common:ROOT:icons/datastax/streaming.svg[role="mx-auto max-w-xs md:mx-0 lg:max-w-none"] +# Manage databases +astra db create my_db -r us-east1 -

Manage {astra_stream}

+# Manage streaming tenants +astra streaming list - - -
- xref:astra-streaming-cli.adoc[] -
+# Run built-in utilities +astra db cqlsh start my_db +astra streaming pulsar shell my_tenant +---- +[subs="macros,attributes"] +++++
++++ diff --git a/modules/ROOT/pages/install.adoc b/modules/ROOT/pages/install.adoc new file mode 100644 index 0000000..c3d08f7 --- /dev/null +++ b/modules/ROOT/pages/install.adoc @@ -0,0 +1,227 @@ += Install the {product} +:navtitle: Install the CLI +:page-aliases: ROOT:installation.adoc, ROOT:getting-started.adoc +:description: {product} makes it easier to integrate {product-short} into your applications and workflows by letting you perform common platform tasks for {astra_db} and {astra_stream} from the command line. + +Install the {product} to create and manage {astra_db} databases and {astra_stream} tenants from the command line. + +== Supported platforms + +The {product} supports the following operating systems: + +[cols="1,2"] +|=== +|Operating System |Architecture + +|Linux +|`x86_64`, `arm64` + +|macOS +|`x86_64`, `arm64` + +|Microsoft Windows +|`x86_64` +|=== + +== Install the CLI + +[tabs,sync-group-id=platforms] +====== +macOS and Linux:: ++ +Select one of the following installation methods to install the {product} on macOS and Linux. +If you prefer to use a package manager, follow the Homebrew instructions instead. ++ +[tabs] +===== +Scripted installation (recommended):: ++ +-- +. Run the following command to install the latest version of the {product} to the default location: ++ +[source,shell] +---- +curl -sSL ibm.biz/astra-cli | sh +---- ++ +.Install to a custom location +[%collapsible] +==== +To install the {product} to a custom location, export the `ASTRA_HOME` environment variable before running the installation command: + +[source,bash,subs="+quotes"] +---- +export ASTRA_HOME=**INSTALLATION_DIRECTORY** +---- + +Replace `**INSTALLATION_DIRECTORY**` with the full path to your preferred installation directory. +==== + +. Add the following lines to your shell profile (for example, `~/.zprofile` or `~/.bash_profile`) to make the `astra` command executable from any directory: ++ +[source,bash] +---- +# Astra CLI shell configuration +eval "$(~/.astra/cli/astra shellenv)" +---- + +. Reload your shell profile or open a new terminal window. + +. Run the `astra` command from any directory to verify successful installation: ++ +[source,shell] +---- +astra +---- ++ +The response includes available commands and options for the {product}. +-- + +Binary installation:: ++ +-- +. Download the appropriate binary archive for your OS and CPU architecture from https://github.com/datastax/astra-cli/releases[GitHub]. + +. Extract the archive into the directory where you want to install the {product}. +For example: ++ +[source,shell,subs="+quotes"] +---- +sudo tar -xzvf astra-**OS**-**ARCHITECTURE**.tar.gz -C **INSTALLATION_DIRECTORY** +---- ++ +Replace the following: ++ +* `**OS**`: Your operating system (`macos` or `linux`). +* `**ARCHITECTURE**`: Your CPU architecture (`x86_64` or `arm64`). +* `**INSTALLATION_DIRECTORY**`: The full path to your preferred installation directory. + +. Add the following lines to your shell profile (for example, `~/.zprofile` or `~/.bash_profile`) to make the `astra` command executable from any directory: ++ +[source,bash,subs="+quotes"] +---- +# Astra CLI shell configuration +eval "$(**PATH_TO_BINARY** shellenv)" +---- ++ +Replace `**PATH_TO_BINARY**` with the full path to the `astra` executable in the installation directory. + +. Required on macOS: Delete the `com.apple.quarantine` attribute from the `astra` binary to remove https://support.apple.com/guide/security/gatekeeper-and-runtime-protection-sec5599b66df/web[macOS Gatekeeper restrictions]: ++ +[source,shell] +---- +xattr -d com.apple.quarantine $(which astra) +---- ++ +Alternatively, you can remove these restrictions in your https://support.apple.com/en-us/102445#openanyway[macOS System Settings]. ++ +If you don't remove the restrictions, you will receive a security alert stating `“astra” Not Opened` when you run the `astra` command. + +. Reload your shell profile or open a new terminal window. + +. Run the `astra` command from any directory to verify successful installation: ++ +[source,shell] +---- +astra +---- ++ +The response includes available commands and options for the {product}. +-- +===== + +Windows:: ++ +Select one of the following installation methods to install the {product} on Windows: ++ +[tabs] +===== +Scripted installation (recommended):: ++ +-- +. Run the following command to install the latest version of the {product} to the default location: ++ +[source,powershell] +---- +powershell -c "irm ibm.biz/astra-cli-win | iex" +---- ++ +.Install to a custom location +[%collapsible] +==== +To install the {product} to a custom location, export the `ASTRA_HOME` environment variable before running the installation command: + +[source,powershell,subs="+quotes"] +---- +$env:ASTRA_HOME = "**INSTALLATION_DIRECTORY**" +---- + +Replace `**INSTALLATION_DIRECTORY**` with the full path to your preferred installation directory. +==== + +. Open a new terminal window. + +. Run the `astra` command from any directory to verify successful installation: ++ +[source,powershell] +---- +astra +---- ++ +The response includes available commands and options for the {product}. +-- + +Binary installation:: ++ +-- +. Download the `windows` zip file from https://github.com/datastax/astra-cli/releases[GitHub]. + +. Extract the zip file into the directory where you want to install the {product}: ++ +[source,powershell,subs="+quotes"] +---- +powershell -C "Expand-Archive -Path astra-windows-x86_64.zip -DestinationPath **INSTALLATION_DIRECTORY** -Force" +---- ++ +Replace `**INSTALLATION_DIRECTORY**` with the full path to your preferred installation directory. + +. Add the path to the unzipped `astra.exe` file to your `PATH` environment variable. +For more information, see the https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_environment_variables[Microsoft PowerShell documentation]. + +. Start a new PowerShell session by opening a new terminal window. + +. Run the `astra` command from any directory to verify successful installation: ++ +[source,powershell] +---- +astra +---- ++ +The response includes available commands and options for the {product}. +-- +===== + +Homebrew:: ++ +-- +. Install the latest version of the {product} using https://brew.sh/[Homebrew]: ++ +[source,shell] +---- +brew install datastax/astra-cli/astra +---- + +. Run the `astra` command from any directory to verify successful installation: ++ +[source,shell] +---- +astra +---- ++ +The response includes available commands and options for the {product}. +-- +====== + +== Next steps + +To connect to {product-short} and run your first commands, see xref:manage-cli.adoc[]. diff --git a/modules/ROOT/pages/installation.adoc b/modules/ROOT/pages/installation.adoc deleted file mode 100644 index ee1fc4d..0000000 --- a/modules/ROOT/pages/installation.adoc +++ /dev/null @@ -1,595 +0,0 @@ -= Install or update the {product} -:description: {product} makes it easier to integrate {product-short} into your applications and workflows by letting you perform common platform tasks for {astra_db} and {astra_stream} from the command line. - -Install the {product} to create and manage {astra_db} databases and {astra_stream} tenants from the command line. - -== Platform compatibility - -The {product} supports the following operating systems: - -[cols="1,2"] -|=== -|Operating System |Architecture - -|Linux -|x86_64 - -|macOS -|x86_64, ARM64 - -|Microsoft Windows -|x86_64 - -_Requires https://learn.microsoft.com/en-us/windows/wsl/install[Windows Subsystem for Linux (WSL)]_ -|=== - -== Install the {product} - -Install the {product} using your preferred method: - -[tabs,id=install] -====== -Homebrew:: -+ --- -You can use Homebrew to install the {product} on macOS and Linux: - -. On macOS, set your macOS app security settings to https://support.apple.com/en-us/102445#openanyway[Allow applications from App Store & Known Developers]. - -. Make sure https://brew.sh/[Homebrew] is installed. - -. Make sure Homebrew is up to date: -+ -[source,bash] ----- -brew update ----- - -. Install the {product}: -+ -[source,bash] ----- -brew install datastax/astra-cli/astra-cli ----- -+ -.Result -[%collapsible] -==== -[source,console,subs="+attributes"] ----- -==> Fetching datastax/astra-cli/astra-cli -==> Downloading https://github.com/datastax/astra-cli/releases/download/{product-version}/astra-cli-{product-version}.arm64_sonoma.bottle.tar.gz -Already downloaded: /Users/USERNAME/Library/Caches/Homebrew/downloads/ca763b5f440dad257d707b2e705e98bd5a66912662fa95ae5ef417e749a2b08a--astra-cli-{product-version}.arm64_sonoma.bottle.tar.gz -==> Installing astra-cli from datastax/astra-cli -==> Pouring astra-cli-{product-version}.arm64_sonoma.bottle.tar.gz -==> Caveats ------------------------- - ENABLE AUTOCOMPLETION -------------------------- -To enable Bash completion for Astra CLI (and other brew formulae when enabled), add the following to your shell configuration file (e.g. ~/.zshrc): - -if [ -f /opt/homebrew/etc/bash_completion.d ]; then - . /opt/homebrew/etc/bash_completion.d -fi - -Once added, reload your shell or run: - -source /opt/homebrew/etc/bash_completion.d - -This will ensure the Bash completion script for Astra CLI is loaded. - -------------------- - SPECIAL COMMANDS -------------------- - -- CQLSH: You must have python 3.7+ but less than 3.12, cqlsh is still not compatible with 3.12, downgrade if needed -- DSBULK: You must have java11+ installm the cli is pulling regular dsbulk - -==> Summary -🍺 /opt/homebrew/Cellar/astra-cli/{product-version}: 4 files, 44.4MB -==> Running `brew cleanup astra-cli`... -Disable this behaviour by setting HOMEBREW_NO_INSTALL_CLEANUP. -Hide these hints with HOMEBREW_NO_ENV_HINTS (see `man brew`). ----- -==== - -. Confirm that the {product} is installed: -+ -[source,bash] ----- -astra --version ----- -+ -.Result -[%collapsible] -==== -The command returns the {product} version that is installed: - -[source,console,subs="+attributes"] ----- -{product-version} ----- -==== -+ -include::ROOT:partial$macos-security-notice.adoc[] - -. Optional: If you haven't done so already, enable https://docs.brew.sh/Shell-Completion[`brew` shell completion]. -+ -The {product} Homebrew formula installs a completion file named `astra` in the Homebrew-managed completions directory. -If you have shell completion enabled in Homebrew, your terminal will automatically suggest and complete {product} commands and options as you type them. --- - -curl:: -+ --- -You can use `curl` to install the {product} on Linux, macOS, and Windows Subsystem for Linux (WSL): - -. Install the {product}: -+ -[source,bash] ----- -curl -Ls "https://dtsx.io/get-astra-cli" | bash ----- -+ -.Result -[%collapsible] -==== -[source,console,subs="+attributes"] ----- - - _____ __ - / _ \ _______/ |_____________ - / /_\ \ / ___/\ __\_ __ \__ \ - / | \___ \ | | | | \// __ \_ - \____|__ /____ > |__| |__| (____ / - \/ \/ \/ - -Installing Astra Cli {product-version} please wait... - -Checking prerequisites: -[OK] - Ready to install. -[OK] - unzip command is available -[OK] - curl command is available - -Preparing directories: -[OK] - Created /home/USERNAME/.astra/tmp -[OK] - Created /home/USERNAME/.astra/cli -[OK] - Created /home/USERNAME/.astra/scb - -Downloading archive: -######################################################################## 100.0% -[OK] - File downloaded -[OK] - Integrity of the archive checked - -Extracting and installation: -[OK] - Extraction is successful -[OK] - File moved to /home/USERNAME/.astra/cli -[OK] - Installation cleaned up -[OK] - astra added to /home/USERNAME/.bashrc -[OK] - astra added to /home/USERNAME/.zshrc -[OK] - Installation Successful - -Open A NEW TERMINAL and run: astra setup - -You can close this window. ----- -==== -+ -The `~/.astra/cli` folder is added to the `PATH` environment variable. -See <> for more information. - -. Open a new terminal or restart your existing terminal. - -. Confirm that the {product} is installed: -+ -[source,bash] ----- -astra --version ----- -+ -.Result -[%collapsible] -==== -The command returns the {product} version that is installed: - -[source,console,subs="+attributes"] ----- -{product-version} ----- -==== -+ -include::ROOT:partial$macos-security-notice.adoc[] --- - -JVM:: -+ --- -The {product} is available as a packaged Java application that you can use on any machine running a JVM. - -To run the {product} in a JVM, you must have Java 17+ installed. -You can install Java by downloading and installing the latest https://www.oracle.com/java/technologies/downloads/[Oracle JDK] - -. Verify that Java is version 17 or higher: -+ -[source,bash] ----- -java --version ----- - -. Download the latest release of https://github.com/datastax/astra-cli/releases[astra-cli] image:https://img.shields.io/github/v/release/datastax/astra-cli?label=latest&color=green[alt="Latest astra-cli release on GitHub",link="https://github.com/datastax/astra-cli/releases"]: -+ -[source,bash,subs="+attributes"] ----- -curl -L -o astra-cli-{product-version}.zip https://github.com/datastax/astra-cli/releases/download/{product-version}/astra-cli-{product-version}.zip ----- - -. Unzip the archive: -+ -[source,bash,subs="+attributes"] ----- -unzip astra-cli-{product-version}.zip -d ./astra-cli-{product-version} && cd astra-cli-{product-version} ----- - -. Confirm that you can successfully run the {product}: -+ -[source,bash] ----- -java -jar astra-cli.jar --version ----- -+ -.Result -[%collapsible] -==== -The command returns the {product} version that is installed: - -[source,console,subs="+attributes"] ----- -{product-version} ----- -==== - -You can use all options and suffixes on commands when running the JAR file. -For example: - -[source,bash] ----- -java -jar ./astra-cli.jar db list --token AstraCS:FZm... ----- --- - -Docker:: -+ --- -The {product} is available as an https://hub.docker.com/r/datastax/astra-cli[official Docker image] that you can run in a container. - -To install the {product} using Docker, you must have https://docs.docker.com/engine/install/[Docker engine] or https://www.docker.com/products/docker-desktop[Docker desktop] installed. - -. Confirm that Docker is installed and running: -+ -[source,bash] ----- -docker --version ----- -+ -.Result -[%collapsible] -==== -The command returns the Docker version that is installed: - -[source,console] ----- -Docker version 27.1.1, build 6312585 ----- -==== - -. Pull the latest {product} Docker image (`datastax/astra-cli:latest`): -+ -[source,bash,subs="+attributes"] ----- -docker pull datastax/astra-cli ----- -+ -[TIP] -==== -To pull a specific version of the Docker image, run `docker pull datastax/astra-cli:**TAG**`, replacing `**TAG**` with the version tag of the Docker image you want to pull. -==== -+ -.Result -[%collapsible] -==== -[source,console] ----- -Using default tag: latest -latest: Pulling from datastax/astra-cli -7890eb226106: Pull complete -f4455e290156: Pull complete -e6c3f5cd9c43: Pull complete -322cfd5270ff: Pull complete -Digest: sha256:8dcba8115cbae7bcabfc579341611f30860239ee5edbca3938edea4542ca06fb -Status: Downloaded newer image for datastax/astra-cli:latest -docker.io/datastax/astra-cli:latest - -What's next: - View a summary of image vulnerabilities and recommendations → docker scout quickview datastax/astra-cli ----- -==== - -. Confirm that you can successfully run the {product} in a Docker container: -+ -[source,bash] ----- -docker run -rm datastax/astra-cli --version ----- -+ -.Result -[%collapsible] -==== -The command returns the {product} version that is installed: - -[source,console,subs="+attributes"] ----- -{product-version} ----- -==== - -. Optional: Run the {product} with a configuration file: -+ -[source,bash,subs="+quotes"] ----- -docker run -rm -v **CONFIG_FILE**:/work/.astrarc datastax/astra-cli --version ----- -+ -Replace `**CONFIG_FILE**`with the path to your {product} configuration file. -For example: -+ -[source,bash] ----- -docker run -rm -v ~/.astrarc:/work/.astrarc datastax/astra-cli --version ----- -+ -This command mounts the `~/.astrarc` file from your local machine to the `/work/.astrarc` file in the Docker container. -This lets you use your local configuration file when running the {product} in a Docker container. - -. Optional: Create a shell alias for running the {product} in a Docker container. -+ -You can create a shell alias to eliminate the need to include the `docker run` command whenever you want to run the {product} in a Docker container. -For example, the following command creates an alias named `astra`: -+ -[source,bash] ----- -alias astra='docker run -rm -v ~/.astrarc:/work/.astrarc datastax/astra-cli' ----- -+ -You can run this command in your terminal to create a temporary alias for the current session, or you can add it to your shell configuration file so that the alias is available in every new terminal session. -+ -After you add the alias, you can use it to run {product} commands in a Docker container using the same syntax as the `astra` binary: -+ -[source,bash] ----- -astra --version ----- --- -====== - -To set up a new configuration and run your first commands, see xref:getting-started.adoc[]. - -[#file-locations] -=== Installation file locations - -The {product} and its configuration are installed in the following locations: - -[cols="1,2"] -|=== -|File location |Description - -|`~/.astra` -a|The {product} installation directory. - -For <>, the `astra` executable and `astra-init.sh` auto-completion script are located in `~/.astra/cli`. -The `~/.astra/cli` folder is added to the `PATH` environment variable. -_This folder is deleted and recreated when you update or re-install the {product}._ - -For <>, the `astra` executable and auto-completion script are located in https://docs.brew.sh/FAQ#why-should-i-install-homebrew-in-the-default-location[Homebrew's default prefix] at the following locations: - -* Executable: `HOMEBREW_PREFIX/Cellar/astra-cli/VERSION/bin/astra` -* Auto-completion script: `HOMEBREW_PREFIX/Cellar/astra-cli/VERSION/etc/bash_completion.d/astra` - -|`~/.astrarc` -|The {product} configuration file. - -_This file is *not* deleted when you update or re-install the {product}._ -|=== - -== Update the {product} - -To update the {product}, follow the procedure for the method you used to originally install the {product}: - -[tabs] -====== -Homebrew:: -+ --- -. Make sure Homebrew is up to date: -+ -[source,bash] ----- -brew update ----- - -. Update the {product}: -+ -[source,bash] ----- -brew upgrade datastax/astra-cli/astra-cli ----- -+ -.Result -[%collapsible] -==== -[source,console] ----- -==> Upgrading datastax/astra-cli/astra-cli - 0.5 -> 0.6 -==> Pouring astra-cli-0.6.arm64_sonoma.bottle.tar.gz -==> Caveats ------------------------- - ENABLE AUTOCOMPLETION -------------------------- -To enable Bash completion for Astra CLI (and other brew formulae when enabled), add the following to your shell configuration file (e.g. ~/.zshrc): - -if [ -f /opt/homebrew/etc/bash_completion.d ]; then - . /opt/homebrew/etc/bash_completion.d -fi - -Once added, reload your shell or run: - -source /opt/homebrew/etc/bash_completion.d - -This will ensure the Bash completion script for Astra CLI is loaded. - -------------------- - SPECIAL COMMANDS -------------------- - -- CQLSH: You must have python 3.7+ but less than 3.12, cqlsh is still not compatible with 3.12, downgrade if needed -- DSBULK: You must have java11+ installm the cli is pulling regular dsbulk - -==> Summary -🍺 /opt/homebrew/Cellar/astra-cli/0.6: 4 files, 44.4MB -==> Running `brew cleanup astra-cli`... -Removing: /opt/homebrew/Cellar/astra-cli/0.5... (4 files, 61.7MB) -Removing: /Users/USERNAME/Library/Caches/Homebrew/astra-cli--0.5.arm64_sonoma.bottle.tar.gz... (24.4MB) ----- -==== - -. Confirm that the latest version of the {product} is installed: -+ -[source,bash] ----- -astra --version ----- -+ -.Result -[%collapsible] -==== -The command returns the {product} version that is installed: - -[source,console,subs="+attributes"] ----- -{product-version} ----- -==== -+ -include::ROOT:partial$macos-security-notice.adoc[] --- - -curl:: -+ --- -. Update the {product}: -+ -[source,bash] ----- -curl -Ls "https://dtsx.io/get-astra-cli" | bash ----- - -. Confirm that the latest version of the {product} is installed: -+ -[source,bash] ----- -astra --version ----- -+ -.Result -[%collapsible] -==== -The command returns the {product} version that is installed: - -[source,console,subs="+attributes"] ----- -{product-version} ----- -==== --- -====== - -== Uninstall the {product} - -To uninstall the {product}, follow the procedure for the method you used to originally install the {product}: - -[tabs] -====== -Homebrew:: -+ --- -. Uninstall the {product}: -+ -[source,bash] ----- -brew uninstall datastax/astra-cli/astra-cli ----- -+ -.Result -[%collapsible] -==== -[source,console,subs="+attributes"] ----- -Uninstalling /opt/homebrew/Cellar/astra-cli/{product-version}... (4 files, 61.7MB) ----- -==== - -. Delete the {product} and its associated installation files: -+ -[source,bash] ----- -rm -R ~/.astra ----- - -. Optional: Delete the {product} configuration file: -+ -[source,bash] ----- -rm ~/.astrarc ----- --- - -curl:: -+ --- -. Delete the {product} and its associated installation files: -+ -[source,bash] ----- -rm -R ~/.astra ----- - -. Optional: Delete the {product} configuration file: -+ -[source,bash] ----- -rm ~/.astrarc ----- - -. Optional: Remove the {product} from your shell configuration file, such as `.zshrc` or `.bashrc`: - -.. Open your shell configuration file in a text editor. -For example: -+ -[source,bash] ----- -nano ~/.zshrc ----- - -.. Remove any lines that reference the {product}. -For example: -+ -[source,bash] ----- -#THIS MUST BE AT THE END OF THE FILE FOR ASTRA_CLI TO WORK!!! -export ASTRADIR="/Users/USERNAME/.astra/cli" -[[ -s "/Users/USERNAME/.astra/cli/astra-init.sh" ]] && source "/Users/USERNAME/.astra/cli/astra-init.sh" ----- - -.. Save and close the file. --- -====== \ No newline at end of file diff --git a/modules/ROOT/pages/manage-cli.adoc b/modules/ROOT/pages/manage-cli.adoc new file mode 100644 index 0000000..e20a54d --- /dev/null +++ b/modules/ROOT/pages/manage-cli.adoc @@ -0,0 +1,572 @@ += Connect and manage the {product} +:navtitle: Connect and manage the CLI +:page-aliases: ROOT:managing.adoc, ROOT:astra-streaming-cli.adoc, ROOT:administration.adoc + +//// +Author's note: The following pages used to serve as de facto command references: + +ROOT:managing.adoc, ROOT:astra-streaming-cli.adoc, ROOT:administration.adoc + +However, since the new command reference pages are programmatically generated, there isn't a good place to redirect them to (yet). +Once we have quickstarts for Astra DB, Astra Streaming, and Astra administration, we can move the page aliases. +//// + +Learn how to connect and run commands with the {product}. + +If you haven't installed the {product} yet, see xref:ROOT:install.adoc[]. + +== Get an application token + +The {product} requires an xref:astra-db-serverless:administration:manage-application-tokens.adoc[application token] to connect to {product-short}. + +xref:astra-db-serverless:administration:manage-application-tokens.adoc#org-token[Generate an application token] and copy the token string (`AstraCS:…`) before moving on to the next section. + +[TIP] +==== +If this is your first time using the {product}, {company} recommends that you connect to a non-production organization first. +That way, you can assign your application token a more expansive role, such as *Organization Administrator*, so that you can try out all of the {product}'s features without putting production data at risk. + +If you're using the {product} in production, {company} strongly recommends that you follow the principle of least privilege: Make sure your application token's role provides only the minimum required permissions. +For example, don't grant an administrator-level role to a token that won't be used to execute those types of commands. +==== + +//TODO: Turn this section into tabs +[#connect-to-astra] +== Connect the {product} + +You can configure the {product} to authenticate in the following ways: + +Save configuration profiles:: +Configuration profiles let you save and manage connection information for use in {product} sessions. ++ +Each configuration profile consists of a name and an application token. +When you set a profile as the default, the {product} authenticates all commands using that profile's application token, unless overridden. ++ +See <>. + +Authenticate individual commands:: +You can supply an application token to authenticate individual commands. ++ +This method is useful if you want to run a command without having to create a configuration profile. ++ +See <>. + +[#create-first-configuration-profile] +=== Create your first configuration profile + +The following procedure describes how to create your first configuration profile interactively, and is recommended for users who are new to the {product}. + +For more advanced methods of creating and managing configuration profiles, see <>. + +. Run the `xref:commands:astra-setup.adoc[]` command: ++ +[source,shell] +---- +astra setup +---- ++ +.Result +[%collapsible%open] +==== +[source,console] +---- + _____ __ + / _ \ _______/ |_____________ + / /_\ \ / ___/\ __\_ __ \__ \ + / | \\___ \ | | | | \ //__ \_ + \____|__ /____ > |__| |__| (____ / + \/ \/ \/ + + Version: x.x.x + +Welcome to the interactive Astra CLI setup! + +Your configuration file will be created at /Users/username/.astrarc + +Press Enter to continue, or use Ctrl+C to cancel. +---- +==== + +. Press kbd:[Enter] to continue. ++ +.Result +[%collapsible%open] +==== +[source,console] +---- +(Required) Enter your Astra token (it should start with AstraCS) +> input hidden for security +---- +==== + +. Enter your application token (`AstraCS:...`), and then press kbd:[Enter]. ++ +.Result +[%collapsible%open] +==== +[source,console] +---- +(Optional) Enter a name for your profile (defaults to your org name) +> +---- +==== + +. Enter a name for your configuration profile, or press kbd:[Enter] to accept the default (your organization name). ++ +.Result +[%collapsible] +==== +[source,console] +---- +Profile 'PROFILE_NAME' successfully created. + +It has been set as the default profile. +---- +==== ++ +The {product} automatically sets the configuration profile as the default. +All subsequent commands use this profile unless you <>. + +. Run a command to test the connection. +For example: ++ +[source,shell] +---- +astra db list-clouds +---- ++ +.Result +[%collapsible] +==== +[source,console] +---- +┌─────────────────┐ +│ Cloud Provider │ +├─────────────────┤ +│ gcp │ +│ azure │ +│ aws │ +└─────────────────┘ +---- +==== ++ +If the command succeeds, your connection is configured correctly. + +[#authenticate-individual-command] +=== Authenticate an individual command + +Every command lets you supply an application token using the `--token` option. +This option is useful if you want to run a command without having to create a configuration profile. + +For example: + +[source,shell,subs="+quotes"] +---- +astra user list --token **APPLICATION_TOKEN** +---- + +The `--token` option bypasses the default configuration profile (if one exists) and uses the supplied application token for that command only. + +Alternatively, if you have multiple application tokens saved in different configuration profiles, you can specify a configuration profile for an individual command. +See <>. + +== Get command help + +Run `astra` by itself to print general help information: + +[source,shell] +---- +astra +---- + +.Result +[%collapsible] +==== +[source,console] +---- + _____ __ + / _ \ _______/ |_____________ + / /_\ \ / ___/\ __\_ __ \__ \ + / | \\___ \ | | | | \ //__ \_ + \____|__ /____ > |__| |__| (____ / + \/ \/ \/ + + Version: x.x.x + +Documentation: https://docs.datastax.com/en/astra-cli + +Usage: astra [-qVv] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [COMMAND] + + -v, --version Print version information and exit. + (default: false) + +Common Options: + --color=WHEN One of: auto, never, always + (default: auto) + --dump-logs[=FILE] Write all logs to an optionally specified file + (default: ~/.astra/logs/.log) + --no-input Don't ask for user input (e.g. confirmation prompts) + -o, --output=FORMAT One of: human, json, csv + (default: human) + -q, --quiet Only output essential information + --[no-]spinner Enable/disable loading spinners + (default: enabled if tty) + -V, --verbose Enable verbose logging output + +Commands: + setup Interactively set up the Astra CLI and create profiles + config Manage your Astra CLI configuration profiles + db Manage your Astra databases + pcu Manage your PCU groups and associations + org Get organization information + role Discover Astra roles + streaming Manage Astra streaming tenants + token Manage your Astra tokens + user Manage users in your organization + upgrade Upgrade your Astra CLI installation + shellenv Completions, configuration, and more + nuke Entirely delete Astra CLI from your system + +Examples: + # Create a new profile + $ astra setup + + # List databases + $ astra db list + + # Create a vector database + $ astra db create demo -r us-east1 + +See 'astra --help' for help on a specific subcommand. +---- +==== + +Append the `-h` / `--help` option to any command or subcommand to get specific help information and examples: + +[source,shell] +---- +astra org -h +---- + +.Result +[%collapsible] +==== +[source,console] +---- +Usage: astra org [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [COMMAND] + +Get organization information + +The --token flag is handy to quickly get information about another organization. + +Use the --token @file syntax to read the token from a file, to avoid potential +leaks. + + +Common Options: + --color=WHEN One of: auto, never, always + (default: auto) + --dump-logs[=FILE] Write all logs to an optionally specified file + (default: ~/.astra/logs/.log) + --no-input Don't ask for user input (e.g. confirmation prompts) + -o, --output=FORMAT One of: human, json, csv + (default: human) + -q, --quiet Only output essential information + --[no-]spinner Enable/disable loading spinners + (default: enabled if tty) + -V, --verbose Enable verbose logging output + +Connection Options: + -cf, --config-file=PATH + The .astrarc file to use for this command + (default: ~/.astrarc) + --env=ENV Override the target astra environment + -p, --profile=NAME The .astrarc profile to use for this command + --token=TOKEN The astra token to use for this command. Use the + --token @file syntax to read the token from a + file, to avoid potential leaks. + +Commands: + get Get your organization's information + id Get your organization's ID + name Get your organization's name + +Examples: + # Get your organization's information + $ astra org + + # Get information about another organization + $ astra org get --token AstraCS:... + +See 'astra --help' for help on a specific subcommand. +---- +==== + +[source,shell] +---- +astra db list --help +---- + +.Result +[%collapsible] +==== +[source,console] +---- +Usage: astra db list [-qvV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] + +List your non-terminated Astra databases. + + -v, --vector Only show vector-enabled databases + (default: false) + +Common Options: + --color=WHEN One of: auto, never, always + (default: auto) + --dump-logs[=FILE] Write all logs to an optionally specified file + (default: ~/.astra/logs/.log) + --no-input Don't ask for user input (e.g. confirmation prompts) + -o, --output=FORMAT One of: human, json, csv + (default: human) + -q, --quiet Only output essential information + --[no-]spinner Enable/disable loading spinners + (default: enabled if tty) + -V, --verbose Enable verbose logging output + +Connection Options: + -cf, --config-file=PATH + The .astrarc file to use for this command + (default: ~/.astrarc) + --env=ENV Override the target astra environment + -p, --profile=NAME The .astrarc profile to use for this command + --token=TOKEN The astra token to use for this command. Use the + --token @file syntax to read the token from a + file, to avoid potential leaks. + +Examples: + # List all your Astra databases + $ astra db list + + # List only vector-enabled Astra databases + $ astra db list --vector + +See 'astra --help' for help on a specific subcommand. +---- +==== + +[#command-auto-completion] +== Use command auto-completion + +The {product} provides command auto-completion for Bash and ZSH shells. + +To use auto-completion, type the `astra` command and then press kbd:[Tab] twice to get a list of available options: + +[source,shell,subs="+macros"] +---- +% astra kbd:[Tab] kbd:[Tab] +config nuke pcu setup streaming upgrade +db org role shellenv token user +---- + +Certain dynamic arguments, such as database names, also support auto-completion once the {product} discovers them. + +For example, after running `astra db list`, type `astra db get` followed by kbd:[Tab] twice to see a list of your database names: + +[source,shell,subs="+macros"] +---- +% astra db get kbd:[Tab] kbd:[Tab] +prod_db test_db playground_db +---- + +Most dynamic auto-completions are tied to configuration profiles. +When you switch to a different configuration profile, only resources that have been discovered by that profile are available for auto-completion. + +[#manage-configuration-profiles] +== Manage configuration profiles + +Configuration profiles provide a convenient way to save and manage application tokens for <>. +Configuration profiles consist of a name and an application token and are stored in the `<>` configuration file. + +The following sections describe how to create additional configuration profiles, each with their own application token, to make it easier to manage different types of resources across one or more organizations. + +=== List your configuration profiles + +Use the `xref:commands:astra-config-list.adoc[]` command to list all of your configuration profiles: + +[source,shell] +---- +astra config list +---- + +.Result +[%collapsible] +==== +[source,console] +---- +┌─────────────────────┐ +│ configuration │ +├─────────────────────┤ +│ Production (in use) │ +│ Testing │ +└─────────────────────┘ +---- +==== + +The default configuration profile is indicated by `(in use)`. + +Configuration profiles are stored in the following format in the `<>` file: + +..astrarc +[source,ini,subs="+quotes"] +---- +[Production] +ASTRA_DB_APPLICATION_TOKEN=AstraCS:**IGXWg...** + +[default] +ASTRA_DB_APPLICATION_TOKEN=AstraCS:**IGXWg...** + +[Testing] +ASTRA_DB_APPLICATION_TOKEN=AstraCS:WeaYR... +---- + +The `[default]` profile duplicates the application token of the configuration profile that is currently <>. +In the previous example, you can tell the `Production` profile is the default profile because `[Production]` and `[default]` have the same application token. + +=== Create a new configuration profile + +Use the `xref:commands:astra-config-create.adoc[]` command to create a new configuration profile: + +[source,shell,subs="+quotes"] +---- +astra config create '**PROFILE_NAME**' --token **APPLICATION_TOKEN** +---- + +.Result +[%collapsible] +==== +[source,console] +---- +Configuration profile 'PROFILE_NAME' successfully created. + +(Hint: Use 'astra setup' for an interactive profile creation experience!) + +# Set it as the default profile: +$ astra config use 'PROFILE_NAME' +---- +==== + +You can also use the `xref:commands:astra-setup.adoc[]` command again to create additional configuration profiles interactively. + +.Enclose arguments in quotes when they contain spaces +[TIP] +==== +When specifying arguments that contain spaces (for example, profile names like `Test 1`), you must wrap the value in single quotes (`''`). +This ensures that your shell treats the entire phrase as one argument rather than splitting it into separate words. + +For example: + +[source,shell,subs="+quotes"] +---- +astra config create **'Test 1'** --token AstraCS:... +---- + +Without quotes, your shell would interpret `Test` and `1` as two different arguments and cause the command to return an `Unmatched argument` or other similar error. +==== + +[#set-default-configuration-profile] +=== Set the default configuration profile + +Use the `xref:commands:astra-config-use.adoc[]` command to change the default configuration that the {product} uses when executing commands: + +[source,shell,subs="+quotes"] +---- +astra config use '**PROFILE_NAME**' +---- + +.Result +[%collapsible] +==== +[source,console] +---- +Default profile set to 'PROFILE_NAME'. +---- +==== + +[#specify-configuration-profile-individual-command] +=== Specify a configuration profile for an individual command + +Every command lets you specify a configuration profile using the `-p` / `--profile` option. +This method is useful if you want to run a command using a different configuration profile without changing the default configuration profile. + +For example: + +[source,shell,subs="+quotes"] +---- +astra user list --profile '**PROFILE_NAME**' +---- + +The `--profile` option bypasses the default configuration profile and uses the supplied configuration profile for that command only. + +If you want to run a command using an application token directly, without having to create a new profile, see <>. + +=== Delete a configuration profile + +Use the `xref:commands:astra-config-delete.adoc[]` command to delete a configuration profile: + +[source,shell,subs="+quotes"] +---- +astra config delete '**PROFILE_NAME**' +---- + +.Result +[%collapsible] +==== +[source,console] +---- +Profile 'PROFILE_NAME' deleted successfully. +---- +==== + +[NOTE] +==== +If you delete the default configuration profile, the {product} _doesn't_ automatically select a new default configuration profile. +You must use the `xref:commands:astra-config-use.adoc[]` command to set a new default configuration profile. +==== + +[#file-locations] +== {product} file locations + +The {product} stores installation and configuration files in the following locations: + +[cols="1h,2"] +|=== +|File / Directory |Description + +|`.astra` +a|The `ASTRA_HOME` directory. + +_Default location_: `~/.astra` (macOS and Linux), `%USERPROFILE%\.astra` (Windows) + +The {product} stores the following items in this directory: + +* The {product} executable (scripted installations only) +* Accessory executables downloaded by certain commands, such as `xref:commands:astra-db-cqlsh.adoc[]` and `xref:commands:astra-db-dsbulk.adoc[]` +* {scb-brief}s +* Cache files for <> +* Logs + +For more information about the `ASTRA_HOME` directory, see the {product} https://github.com/datastax/astra-cli?tab=readme-ov-file#home-folder-location[README]. + +|`.astrarc` +|The {product} configuration file. + +_Default location_: `~/.astrarc` (macOS and Linux), `%USERPROFILE%\.astrarc` (Windows) + +This file stores your <> and their associated application tokens. + +For more information about the {product} configuration file, see the {product} https://github.com/datastax/astra-cli?tab=readme-ov-file#astrarc-location[README]. +|=== diff --git a/modules/ROOT/pages/uninstall.adoc b/modules/ROOT/pages/uninstall.adoc new file mode 100644 index 0000000..7a30cc4 --- /dev/null +++ b/modules/ROOT/pages/uninstall.adoc @@ -0,0 +1,334 @@ += Uninstall the {product} +:navtitle: Uninstall the CLI + +Follow the instructions for your original installation method to uninstall the {product}. + +[tabs,sync-group-id=platforms] +====== +macOS and Linux:: ++ +Select one of the following methods to uninstall the {product} on macOS and Linux: ++ +[tabs] +===== +`astra nuke` command (recommended):: ++ +-- +. Run the `xref:commands:astra-nuke.adoc[]` command: ++ +[source,shell] +---- +astra nuke +---- ++ +.Result +[%collapsible] +==== +[source,console] +---- + _____ __ + / _ \ _______/ |_____________ + / /_\ \ / ___/\ __\_ __ \__ \ + / | \\___ \ | | | | \ //__ \_ + \____|__ /____ > |__| |__| (____ / + \/ \/ \/ + + Version: x.x.x + +Are you sure you want to entirely delete Astra CLI from your system? + +This action is irreversible and will delete all Astra CLI files from your system. + yes +> no (default) + +↑↓ to navigate, Enter to select, type to filter +---- +==== + +. When prompted to continue, select kbd:[yes] and press kbd:[Enter]. ++ +.Result +[%collapsible] +==== +[source,console] +---- +Do you also want to delete the .astrarc file located at /Users/username/.astrarc? + +(You can still Ctrl+C to safely cancel this operation.) + +Your credentials may be lost if you do. A backup is recommended. + yes +> no (default) +---- +==== + +. Select whether to delete the `xref:ROOT:manage-cli.adoc#file-locations[.astrarc]` file. ++ +Only select kbd:[yes] if you don't want to preserve your xref:ROOT:manage-cli.adoc#manage-configuration-profiles[configuration profiles]. ++ +Press kbd:[Enter] to continue. ++ +.Result +[%collapsible] +==== +[source,console] +---- +Astra CLI Nuke Summary + +Files deleted: +→ /Users/username/.astra (contained binary) + +Shell profiles containing astra: +→ /Users/username/.zprofile + +Files skipped: +→ /Users/username/.astrarc - User chose to keep the file +---- +==== + +. Optional: If the `astra nuke` command found any shell profiles containing references to the `astra` command, you can manually delete these references. +-- + +Manual removal:: ++ +-- +. Optional: If you don't want to preserve your xref:ROOT:manage-cli.adoc#manage-configuration-profiles[configuration profiles], delete the `xref:ROOT:manage-cli.adoc#file-locations[.astrarc]` file: ++ +[source,shell] +---- +rm $(astra config path -p) +---- + +. Delete the xref:ROOT:manage-cli.adoc#file-locations[{product} home directory]: ++ +[source,shell] +---- +rm -rf $(astra config home path -p) +---- + +. Delete the `astra` binary if it still exists: ++ +[source,shell] +---- +rm -f $(which astra) +---- + +. Optional: Manually remove any references to the `astra` command from your shell profile. +For example, from `~/.zprofile` or `~/.bash_profile`. +-- +===== + +Windows:: ++ +Select one of the following methods to uninstall the {product} on Windows: ++ +[tabs] +===== +Uninstaller (recommended):: ++ +-- +Only use this method if you installed the {product} using the xref:ROOT:install.adoc[scripted installer]. + +. Optional: If you don't want to preserve your xref:ROOT:manage-cli.adoc#manage-configuration-profiles[configuration profiles], delete the `xref:ROOT:manage-cli.adoc#file-locations[.astrarc]` file: ++ +[source,powershell] +---- +rm -f $(astra config path -p) +---- + +. In your Windows **Settings**, uninstall the {product} app. +For specific instructions, see https://support.microsoft.com/en-us/windows/uninstall-or-remove-apps-and-programs-in-windows-4b55f974-2cc6-2d2b-d092-5905080eaf98[Uninstall or remove apps and programs in Windows]. +-- + +`astra nuke` command:: ++ +-- +. Run the `xref:commands:astra-nuke.adoc[]` command: ++ +[source,powershell] +---- +astra nuke +---- ++ +.Result +[%collapsible] +==== +[source,console] +---- + _____ __ + / _ \ _______/ |_____________ + / /_\ \ / ___/\ __\_ __ \__ \ + / | \\___ \ | | | | \ //__ \_ + \____|__ /____ > |__| |__| (____ / + \/ \/ \/ + + Version: x.x.x + +Are you sure you want to entirely delete Astra CLI from your system? + +This action is irreversible and will delete all Astra CLI files from your system. + yes +> no (default) + +↑↓ to navigate, Enter to select, type to filter +---- +==== + +. When prompted to continue, select kbd:[yes] and press kbd:[Enter]. ++ +.Result +[%collapsible] +==== +[source,console] +---- +Do you also want to delete the .astrarc file located at ? + +(You can still Ctrl+C to safely cancel this operation.) + +Your credentials may be lost if you do. A backup is recommended. + yes +> no (default) +---- +==== + +. Select whether to delete the `xref:ROOT:manage-cli.adoc#file-locations[.astrarc]` file. ++ +Only select kbd:[yes] if you don't want to preserve your xref:ROOT:manage-cli.adoc#manage-configuration-profiles[configuration profiles]. ++ +Press kbd:[Enter] to continue. ++ +.Result +[%collapsible] +==== +[source,console] +---- +Astra CLI Nuke Summary + +Files deleted: +→ (contained binary) + +Shell profiles containing astra: +→ + +Files skipped: +→ - User chose to keep the file +---- +==== + +. Optional: Manually remove `astra` from your system `PATH`. +For more information, see the https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_environment_variables[Microsoft PowerShell documentation]. +-- + +Manual removal:: ++ +-- +. Optional: If you don't want to preserve your xref:ROOT:manage-cli.adoc#manage-configuration-profiles[configuration profiles], delete the `xref:ROOT:manage-cli.adoc#file-locations[.astrarc]` file: ++ +[source,powershell] +---- +rm -f $(astra config path -p) +---- + +. Delete the xref:ROOT:manage-cli.adoc#file-locations[{product} home directory]: ++ +[source,powershell] +---- +rm -r -f $(astra config home path -p) +---- + +. Delete the `astra` binary if it still exists: ++ +[source,powershell] +---- +rm -f (Get-Command astra).Source +---- + +. Optional: Manually remove `astra` from your system `PATH`. +For more information, see the https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_environment_variables[Microsoft PowerShell documentation]. +-- +===== + +Homebrew:: ++ +-- +. Delete the {product} home directory (`xref:ROOT:manage-cli.adoc#file-locations[~/.astra]`) and optionally its configuration file (`xref:ROOT:manage-cli.adoc#file-locations[~/.astrarc]`): ++ +.. Run the `xref:commands:astra-nuke.adoc[]` command: ++ +[source,shell] +---- +astra nuke +---- ++ +.Result +[%collapsible] +==== +[source,console] +---- + _____ __ + / _ \ _______/ |_____________ + / /_\ \ / ___/\ __\_ __ \__ \ + / | \\___ \ | | | | \ //__ \_ + \____|__ /____ > |__| |__| (____ / + \/ \/ \/ + + Version: x.x.x + +Are you sure you want to entirely delete Astra CLI from your system? + +This action is irreversible and will delete all Astra CLI files from your system. + yes +> no (default) + +↑↓ to navigate, Enter to select, type to filter +---- +==== ++ +.. When prompted to continue, select kbd:[yes] and press kbd:[Enter]. ++ +.Result +[%collapsible] +==== +[source,console] +---- +Do you also want to delete the .astrarc file located at /Users/username/.astrarc? + +(You can still Ctrl+C to safely cancel this operation.) + +Your credentials may be lost if you do. A backup is recommended. + yes +> no (default) +---- +==== ++ +.. Select whether to delete the `xref:ROOT:manage-cli.adoc#file-locations[.astrarc]` file. ++ +Only select kbd:[yes] if you don't want to preserve your xref:ROOT:manage-cli.adoc#manage-configuration-profiles[configuration profiles]. ++ +Press kbd:[Enter] to continue. ++ +.Result +[%collapsible] +==== +[source,console] +---- +Astra CLI Nuke Summary + +Files deleted: +→ /Users/username/.astra + +Files skipped: +→ /Users/username/.astrarc - User chose to keep the file + +To complete the uninstallation, please use Homebrew to uninstall the Astra CLI binary. +---- +==== + +. Uninstall the {product} using Homebrew: ++ +[source,shell] +---- +brew uninstall datastax/astra-cli/astra +---- +-- +====== diff --git a/modules/ROOT/pages/upgrade.adoc b/modules/ROOT/pages/upgrade.adoc new file mode 100644 index 0000000..fc2bb57 --- /dev/null +++ b/modules/ROOT/pages/upgrade.adoc @@ -0,0 +1,90 @@ += Upgrade the {product} +:navtitle: Upgrade the CLI + +Keep the {product} up to date to access new features, improvements, and security updates. + +[IMPORTANT] +==== +If you used a package manager to install the {product}, such as Homebrew, then you must use the same package manager to upgrade the {product}. +==== + +[tabs,sync-group-id=platforms] +====== +macOS and Linux:: ++ +-- +. Run the `xref:commands:astra-upgrade.adoc[]` command to upgrade to the latest version of the {product}: ++ +[source,shell] +---- +astra upgrade +---- + +. Optional: Upgrade to a specific version of the {product}: ++ +[source,shell,subs="+quotes"] +---- +astra upgrade --version **VERSION** +---- ++ +You can also use this command to downgrade to a previous version. + +. Check the {product} version to verify that the upgrade was successful: ++ +[source,shell] +---- +astra --version +---- ++ +The response returns your {product} version. +-- + +Windows:: ++ +-- +. Run the `xref:commands:astra-upgrade.adoc[]` command to upgrade to the latest version of the {product}: ++ +[source,powershell] +---- +astra upgrade +---- + +. Optional: Upgrade to a specific version of the {product}: ++ +[source,powershell,subs="+quotes"] +---- +astra upgrade --version **VERSION** +---- ++ +You can also use this command to downgrade to a previous version. + +. Check the {product} version to verify that the upgrade was successful: ++ +[source,powershell] +---- +astra --version +---- ++ +The response returns your {product} version. +-- + +Homebrew:: ++ +-- +. Run the following command to upgrade to the latest version of the {product}: ++ +[source,shell] +---- +brew upgrade datastax/astra-cli/astra +---- + +. Check the {product} version to verify that the upgrade was successful: ++ +[source,shell] +---- +astra --version +---- ++ +The response returns your {product} version. +-- +====== diff --git a/modules/ROOT/partials/async-option-active.adoc b/modules/ROOT/partials/async-option-active.adoc deleted file mode 100644 index f310874..0000000 --- a/modules/ROOT/partials/async-option-active.adoc +++ /dev/null @@ -1,2 +0,0 @@ -By default, the command runs synchronously and doesn't return the command prompt until the database reaches *Active* or *Error* status. -To run the command _asynchronously_, add the `--async` option. \ No newline at end of file diff --git a/modules/ROOT/partials/macos-security-notice.adoc b/modules/ROOT/partials/macos-security-notice.adoc deleted file mode 100644 index a85b76b..0000000 --- a/modules/ROOT/partials/macos-security-notice.adoc +++ /dev/null @@ -1,10 +0,0 @@ -.macOS security alerts -[IMPORTANT] -==== -The first time you run the `astra` command after installing or updating the {product} on macOS, the operating system may display the following alert: `“astra” Not Opened`. - -image::ROOT:install-macos-security-alert.png[] - -If you encounter this alert, then you must override your Mac security settings before you can run {product} commands. -See the https://support.apple.com/en-us/102445#openanyway[Apple support documentation] for more information. -==== diff --git a/modules/ROOT/partials/partial-nav.adoc b/modules/ROOT/partials/partial-nav.adoc new file mode 100644 index 0000000..f50d1d6 --- /dev/null +++ b/modules/ROOT/partials/partial-nav.adoc @@ -0,0 +1,109 @@ + +.Commands +* xref:commands:astra-setup.adoc[] +* xref:commands:astra-config.adoc[] +** xref:commands:astra-config-list.adoc[] +** xref:commands:astra-config-create.adoc[] +** xref:commands:astra-config-get.adoc[] +** xref:commands:astra-config-delete.adoc[] +** xref:commands:astra-config-rename.adoc[] +** xref:commands:astra-config-use.adoc[] +** xref:commands:astra-config-path.adoc[] +** xref:commands:astra-config-home.adoc[] +*** xref:commands:astra-config-home-path.adoc[] +* xref:commands:astra-db.adoc[] +** xref:commands:astra-db-list.adoc[] +** xref:commands:astra-db-get.adoc[] +** xref:commands:astra-db-create.adoc[] +** xref:commands:astra-db-delete.adoc[] +** xref:commands:astra-db-status.adoc[] +** xref:commands:astra-db-cqlsh.adoc[] +*** xref:commands:astra-db-cqlsh-start.adoc[] +*** xref:commands:astra-db-cqlsh-exec.adoc[] +*** xref:commands:astra-db-cqlsh-version.adoc[] +*** xref:commands:astra-db-cqlsh-path.adoc[] +** xref:commands:astra-db-dsbulk.adoc[] +*** xref:commands:astra-db-dsbulk-count.adoc[] +*** xref:commands:astra-db-dsbulk-load.adoc[] +*** xref:commands:astra-db-dsbulk-unload.adoc[] +*** xref:commands:astra-db-dsbulk-version.adoc[] +*** xref:commands:astra-db-dsbulk-path.adoc[] +** xref:commands:astra-db-create-dotenv.adoc[] +** xref:commands:astra-db-download-scb.adoc[] +** xref:commands:astra-db-resume.adoc[] +** xref:commands:astra-db-list-keyspaces.adoc[] +** xref:commands:astra-db-create-keyspace.adoc[] +** xref:commands:astra-db-delete-keyspace.adoc[] +** xref:commands:astra-db-list-collections.adoc[] +** xref:commands:astra-db-create-collection.adoc[] +** xref:commands:astra-db-describe-collection.adoc[] +** xref:commands:astra-db-delete-collection.adoc[] +** xref:commands:astra-db-truncate-collection.adoc[] +** xref:commands:astra-db-list-tables.adoc[] +** xref:commands:astra-db-describe-table.adoc[] +** xref:commands:astra-db-delete-table.adoc[] +** xref:commands:astra-db-truncate-table.adoc[] +** xref:commands:astra-db-list-embedding-providers.adoc[] +** xref:commands:astra-db-list-cdcs.adoc[] +** xref:commands:astra-db-create-cdc.adoc[] +** xref:commands:astra-db-delete-cdc.adoc[] +** xref:commands:astra-db-create-region.adoc[] +** xref:commands:astra-db-delete-region.adoc[] +** xref:commands:astra-db-list-regions.adoc[] +** xref:commands:astra-db-list-regions-classic.adoc[] +** xref:commands:astra-db-list-regions-serverless.adoc[] +** xref:commands:astra-db-list-regions-vector.adoc[] +** xref:commands:astra-db-list-clouds.adoc[] +** xref:commands:astra-db-get-endpoint-swagger.adoc[] +** xref:commands:astra-db-get-endpoint-api.adoc[] +** xref:commands:astra-db-get-endpoint-playground.adoc[] +* xref:commands:astra-pcu.adoc[] +** xref:commands:astra-pcu-list.adoc[] +** xref:commands:astra-pcu-get.adoc[] +** xref:commands:astra-pcu-status.adoc[] +** xref:commands:astra-pcu-park.adoc[] +** xref:commands:astra-pcu-unpark.adoc[] +** xref:commands:astra-pcu-create.adoc[] +** xref:commands:astra-pcu-update.adoc[] +** xref:commands:astra-pcu-delete.adoc[] +** xref:commands:astra-pcu-associate.adoc[] +** xref:commands:astra-pcu-disassociate.adoc[] +** xref:commands:astra-pcu-list-associations.adoc[] +** xref:commands:astra-pcu-transfer-association.adoc[] +* xref:commands:astra-org.adoc[] +** xref:commands:astra-org-get.adoc[] +** xref:commands:astra-org-id.adoc[] +** xref:commands:astra-org-name.adoc[] +* xref:commands:astra-role.adoc[] +** xref:commands:astra-role-list.adoc[] +** xref:commands:astra-role-get.adoc[] +* xref:commands:astra-streaming.adoc[] +** xref:commands:astra-streaming-list.adoc[] +** xref:commands:astra-streaming-get.adoc[] +** xref:commands:astra-streaming-create.adoc[] +** xref:commands:astra-streaming-delete.adoc[] +** xref:commands:astra-streaming-exist.adoc[] +** xref:commands:astra-streaming-status.adoc[] +** xref:commands:astra-streaming-pulsar.adoc[] +*** xref:commands:astra-streaming-pulsar-shell.adoc[] +*** xref:commands:astra-streaming-pulsar-version.adoc[] +*** xref:commands:astra-streaming-pulsar-path.adoc[] +** xref:commands:astra-streaming-pulsar-token.adoc[] +** xref:commands:astra-streaming-list-regions.adoc[] +** xref:commands:astra-streaming-list-clouds.adoc[] +* xref:commands:astra-token.adoc[] +** xref:commands:astra-token-list.adoc[] +** xref:commands:astra-token-get.adoc[] +** xref:commands:astra-token-create.adoc[] +** xref:commands:astra-token-delete.adoc[] +* xref:commands:astra-user.adoc[] +** xref:commands:astra-user-list.adoc[] +** xref:commands:astra-user-get.adoc[] +** xref:commands:astra-user-invite.adoc[] +** xref:commands:astra-user-delete.adoc[] +* xref:commands:astra-completions.adoc[] +* xref:commands:astra-upgrade.adoc[] +* xref:commands:astra-shellenv.adoc[] +* xref:commands:astra-nuke.adoc[] + + diff --git a/modules/commands/pages/astra-completions.adoc b/modules/commands/pages/astra-completions.adoc new file mode 100644 index 0000000..6c95a6c --- /dev/null +++ b/modules/commands/pages/astra-completions.adoc @@ -0,0 +1,31 @@ += astra completions + +[source,shell] +---- +astra completions [-n=<$cliName>] + +---- + + +See the help for the ``astra shellenv`` command to setup completions in your shell. + +== Aliases + +`astra compgen` + + + + +== Options + +`-n`, `--cli-name`:: CLI name to use in the completion script + + +== Examples +[source,bash] +---- +# Put this in your shell profile (e.g. ``~/.zprofile``) to generate completions and set your PATH +$ eval "$(/path/to/astra shellenv)" +---- + + diff --git a/modules/commands/pages/astra-config-create.adoc b/modules/commands/pages/astra-config-create.adoc new file mode 100644 index 0000000..5b29ccc --- /dev/null +++ b/modules/commands/pages/astra-config-create.adoc @@ -0,0 +1,61 @@ += astra config create + +[source,shell] +---- +astra config create [-dqV] [--no-input] [--[no-]overwrite] [--[no-]spinner] + [--dump-logs[=FILE]] [-cf=PATH] [--color=WHEN] [-e=ENV] + [-o=FORMAT] -t=TOKEN [NAME] + +---- + + +Create a new configuration profile to store your Astra credentials. + +Use the ``--token @`` syntax to securely read the token from a file, without leaking the token to your shell history, where the file contains only the token as plain text or a JSON string. + + + + + +== Options + +`NAME`:: Unique name for the profile +`-cf`, `--config-file`:: The .astrarc file to work with. See ``astra config path -h`` for how this is resolved. +`-t`, `--token`:: Astra token (``AstraCS:...``) or ``@`` to read from file +`-e`, `--env`:: Astra environment the token targets +`-d`, `--default`:: Set the created profile as the default profile. Same as 'config use ' +`--overwrite`:: Overwrite any existing profile with the same name + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + + +== Examples +[source,bash] +---- +# (Recommended) Interactively create a new profile +$ astra setup + +# (Recommended) Securely create a new profile with the token provided from a file +$ astra config create my_profile -t @token.txt + +# Programmatically create a new profile +$ astra config create my_profile -t AstraCS:... + +# Create a new profile with the default name (organization name) +$ astra config create -t AstraCS:... + +# Create a new profile and set it as the default profile +$ astra config create my_profile -t AstraCS:... --default +---- + + diff --git a/modules/commands/pages/astra-config-delete.adoc b/modules/commands/pages/astra-config-delete.adoc new file mode 100644 index 0000000..9e1a20c --- /dev/null +++ b/modules/commands/pages/astra-config-delete.adoc @@ -0,0 +1,47 @@ += astra config delete + +[source,shell] +---- +astra config delete [-qV] [--if-exists] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [-cf=PATH] [--color=WHEN] [-o=FORMAT] + [NAME] + +---- + + +Delete an existing configuration profile. + + + + + +== Options + +`NAME`:: Name of the profile to delete +`-cf`, `--config-file`:: The .astrarc file to work with. See ``astra config path -h`` for how this is resolved. +`--if-exists`:: Do not fail if the profile does not exist + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + + +== Examples +[source,bash] +---- +# Delete a profile named 'my_profile' +$ astra config delete my_profile + +# Delete a profile named 'my_profile' without failing if it does not exist +$ astra config delete my_profile --if-exists +---- + + diff --git a/modules/commands/pages/astra-config-get.adoc b/modules/commands/pages/astra-config-get.adoc new file mode 100644 index 0000000..f163bba --- /dev/null +++ b/modules/commands/pages/astra-config-get.adoc @@ -0,0 +1,54 @@ += astra config get + +[source,shell] +---- +astra config get [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [-cf=PATH] [--color=WHEN] [-k=KEY] [-o=FORMAT] [NAME] + +---- + + +Get the configuration of a profile or a specific key. + +**Warning:** This command may expose your sensitive Astra token. + +== Aliases + +`astra config describe` + + + + +== Options + +`NAME`:: Name of the profile to get +`-cf`, `--config-file`:: The .astrarc file to work with. See ``astra config path -h`` for how this is resolved. +`-k`, `--key`:: Specific configuration key to retrieve + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + + +== Examples +[source,bash] +---- +# Get the configuration of a specific profile +$ astra config get my_profile + +# Prompt for the profile to get the configuration of +$ astra config get + +# Get the value of a specific key in a profile +$ astra config get my_profile --key ASTRA_DB_APPLICATION_TOKEN +---- + + diff --git a/modules/commands/pages/astra-config-home-path.adoc b/modules/commands/pages/astra-config-home-path.adoc new file mode 100644 index 0000000..f10d793 --- /dev/null +++ b/modules/commands/pages/astra-config-home-path.adoc @@ -0,0 +1,58 @@ += astra config home path + +[source,shell] +---- +astra config home path [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [-p | -i] + +---- + + +Prints the expected path of the astra home folder, even if does not exist. + +The folder is resolved in the following order: + + 1. The ``ASTRA_HOME`` environment variable __(e.g. ASTRA_HOME=~/my_folder)__ + + 2. The ``XDG_DATA_HOME`` spec __(e.g. $XDG_DATA_HOME/astra)__ + + 3. The default home directory __(e.g. ~/.astra)__ + +By default, shows informational output when running in a TTY (interactive terminal), and plain path output when piped or redirected. + + + + + +== Options + +`-p`, `--plain`:: Print only the path to the home folder, without additional information (always) +`-i`, `--info`:: Print informational output with context about the path (always) + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + + +== Examples +[source,bash] +---- +# Get information about the path to the astra home folder +$ astra config home path + +# Force only the plain path to the .astrarc file, without additional information +$ astra config home path -p + +# Force informational output even when piped or redirected +$ astra config home path -i +---- + + diff --git a/modules/commands/pages/astra-config-home.adoc b/modules/commands/pages/astra-config-home.adoc new file mode 100644 index 0000000..ec15bfa --- /dev/null +++ b/modules/commands/pages/astra-config-home.adoc @@ -0,0 +1,29 @@ += astra config home + +[source,shell] +---- +astra config home [COMMAND] + +---- + + +All things related to the Astra CLI home folder + + + +== Subcommands + +* xref:astra-config-home-path.adoc[astra config home path] + + +== Options + + + +== Examples +[source,bash] +---- + +---- + + diff --git a/modules/commands/pages/astra-config-list.adoc b/modules/commands/pages/astra-config-list.adoc new file mode 100644 index 0000000..d0b2df8 --- /dev/null +++ b/modules/commands/pages/astra-config-list.adoc @@ -0,0 +1,48 @@ += astra config list + +[source,shell] +---- +astra config list [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [-cf=PATH] [--color=WHEN] [-e=ENV] [-o=FORMAT] + +---- + + +List your Astra CLI configurations. + +== Aliases + +`astra config` + + + + +== Options + +`-cf`, `--config-file`:: The .astrarc file to work with. See ``astra config path -h`` for how this is resolved. +`-e`, `--env`:: Filter by Astra environment + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + + +== Examples +[source,bash] +---- +# List your Astra CLI configurations. +$ astra config list + +# List your Astra CLI configurations for a specific Astra environment. +$ astra config list --env dev +---- + + diff --git a/modules/commands/pages/astra-config-path.adoc b/modules/commands/pages/astra-config-path.adoc new file mode 100644 index 0000000..559071f --- /dev/null +++ b/modules/commands/pages/astra-config-path.adoc @@ -0,0 +1,58 @@ += astra config path + +[source,shell] +---- +astra config path [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [-p | -i] + +---- + + +Prints the expected path of the .astrarc file, even if does not exist. + +The file is resolved in the following order: + + 1. The ``ASTRARC`` environment variable __(e.g. ASTRARC=~/my_folder/.my_rc)__ + + 2. The ``XDG_CONFIG_HOME`` spec __(e.g. $XDG_CONFIG_HOME/astra/.astrarc)__ + + 3. The default home directory __(e.g. ~/.astrarc)__ + +By default, shows informational output when running in a TTY (interactive terminal), and plain path output when piped or redirected. + + + + + +== Options + +`-p`, `--plain`:: Print only the path to the .astrarc file, without additional information (always) +`-i`, `--info`:: Print informational output with context about the path (always) + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + + +== Examples +[source,bash] +---- +# Get information about the path to the .astrarc file +$ astra config path + +# Force only the plain path to the .astrarc file, without additional information +$ astra config path -p + +# Force informational output even when piped or redirected +$ astra config path -i +---- + + diff --git a/modules/commands/pages/astra-config-rename.adoc b/modules/commands/pages/astra-config-rename.adoc new file mode 100644 index 0000000..3d03c8d --- /dev/null +++ b/modules/commands/pages/astra-config-rename.adoc @@ -0,0 +1,46 @@ += astra config rename + +[source,shell] +---- +astra config rename [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [-cf=PATH] [--color=WHEN] [-o=FORMAT] [NAME] NAME + +---- + + +Rename an existing configuration profile. + + + + + +== Options + +`NAME`:: Name of the profile to rename +`NAME`:: New name for the profile +`-cf`, `--config-file`:: The .astrarc file to work with. See ``astra config path -h`` for how this is resolved. + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + + +== Examples +[source,bash] +---- +# Rename a profile from 'old_name' to 'new_name' +$ astra config rename old_name new_name + +# Interactively rename a profile +$ astra config rename +---- + + diff --git a/modules/commands/pages/astra-config-use.adoc b/modules/commands/pages/astra-config-use.adoc new file mode 100644 index 0000000..d8ecba8 --- /dev/null +++ b/modules/commands/pages/astra-config-use.adoc @@ -0,0 +1,45 @@ += astra config use + +[source,shell] +---- +astra config use [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [-cf=PATH] [--color=WHEN] [-o=FORMAT] [NAME] + +---- + + +Sets an existing profile to be used as the default for all commands. Use the ``--default`` option when creating a new profile to set it as the default automatically. + + + + + +== Options + +`NAME`:: Profile to set as default +`-cf`, `--config-file`:: The .astrarc file to work with. See ``astra config path -h`` for how this is resolved. + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + + +== Examples +[source,bash] +---- +# Set an existing profile as the default +$ astra config use my_profile + +# Set a profile as the default when creating it +$ astra config create my_profile -t @token.txt --default +---- + + diff --git a/modules/commands/pages/astra-config.adoc b/modules/commands/pages/astra-config.adoc new file mode 100644 index 0000000..631e7a0 --- /dev/null +++ b/modules/commands/pages/astra-config.adoc @@ -0,0 +1,63 @@ += astra config + +[source,shell] +---- +astra config [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [-cf=PATH] [--color=WHEN] [-e=ENV] [-o=FORMAT] [COMMAND] + +---- + + +Manage your Astra CLI configuration profiles + + +**Alias of `astra config list`** + + +== Subcommands + +* xref:astra-config-list.adoc[astra config list] +* xref:astra-config-create.adoc[astra config create] +* xref:astra-config-get.adoc[astra config get] +* xref:astra-config-delete.adoc[astra config delete] +* xref:astra-config-rename.adoc[astra config rename] +* xref:astra-config-use.adoc[astra config use] +* xref:astra-config-path.adoc[astra config path] +* xref:astra-config-home.adoc[astra config home] + + +== Options + +`-cf`, `--config-file`:: The .astrarc file to work with. See ``astra config path -h`` for how this is resolved. +`-e`, `--env`:: Filter by Astra environment + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + + +== Examples +[source,bash] +---- +# List your configuration profiles +$ astra config + +# Interactively create a new configuration profile +$ astra config setup + +# Programmatically create a new configuration profile +$ astra config create my_profile --token @token.txt + +# Set an existing configuration profile as default +$ astra config use my_profile +---- + + diff --git a/modules/commands/pages/astra-db-cqlsh-exec.adoc b/modules/commands/pages/astra-db-cqlsh-exec.adoc new file mode 100644 index 0000000..31d599b --- /dev/null +++ b/modules/commands/pages/astra-db-cqlsh-exec.adoc @@ -0,0 +1,64 @@ += astra db cqlsh exec + +[source,shell] +---- +astra db cqlsh exec [-qV] [--debug] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [--connect-timeout=TIMEOUT] + [--encoding=ENCODING] [-f=FILE] [-k=KEYSPACE] [-o=FORMAT] + [-r=REGION] [--request-timeout=TIMEOUT] [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] [DB] [STATEMENT] + +---- + + +Execute CQL statements for your db using cqlsh + + + + + +== Options + +`DB`:: The name/ID of the Astra database to connect to +`STATEMENT`:: Execute the statement and quit +`--debug`:: Show additional debugging information +`--encoding`:: Output encoding (default: utf8) +`--connect-timeout`:: Connection timeout in seconds +`-k`, `--keyspace`:: Authenticate to the given keyspace +`--request-timeout`:: Request timeout in seconds +`-r`, `--region`:: The region to use. Uses the db's default region if not specified. +`-f`, `--file`:: Execute commands from a CQL file, then exit + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Execute a CQL statement +$ astra db cqlsh exec my_db "SELECT * FROM my_keyspace.my_table" + +# Execute a CQL file +$ astra db cqlsh exec my_db -f script.cql +---- + + diff --git a/modules/commands/pages/astra-db-cqlsh-path.adoc b/modules/commands/pages/astra-db-cqlsh-path.adoc new file mode 100644 index 0000000..940b11a --- /dev/null +++ b/modules/commands/pages/astra-db-cqlsh-path.adoc @@ -0,0 +1,57 @@ += astra db cqlsh path + +[source,shell] +---- +astra db cqlsh path [-qV] [--if-exists] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + +---- + + +Get the path to the currently installed cqlsh executable + + + + + +== Options + +`--if-exists`:: Only return path if cqlsh exists, don't install automatically + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Get the path to the cqlsh executable +$ astra db cqlsh path + +# Use the cqlsh exe to run a custom command +$ $(astra db cqlsh path) --help + +# Get path only if cqlsh exists, don't install +$ astra db cqlsh path --if-exists +---- + + diff --git a/modules/commands/pages/astra-db-cqlsh-start.adoc b/modules/commands/pages/astra-db-cqlsh-start.adoc new file mode 100644 index 0000000..fe2a0dd --- /dev/null +++ b/modules/commands/pages/astra-db-cqlsh-start.adoc @@ -0,0 +1,62 @@ += astra db cqlsh start + +[source,shell] +---- +astra db cqlsh start [-qV] [--debug] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [--connect-timeout=TIMEOUT] + [--encoding=ENCODING] [-k=KEYSPACE] [-o=FORMAT] + [-r=REGION] [--request-timeout=TIMEOUT] [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] [] [DB] + +---- + + +Connect to your Astra database using cqlsh + + + + + +== Options + +`DB`:: The name/ID of the Astra database to connect to +`--debug`:: Show additional debugging information +`--encoding`:: Output encoding (default: utf8) +`--connect-timeout`:: Connection timeout in seconds +`-k`, `--keyspace`:: Authenticate to the given keyspace +`--request-timeout`:: Request timeout in seconds +`-r`, `--region`:: The region to use. Uses the db's default region if not specified. + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Launch cqlsh for a database +$ astra db cqlsh start my_db + +# Launch cqlsh with a specific keyspace +$ astra db cqlsh start my_db -k my_keyspace +---- + + diff --git a/modules/commands/pages/astra-db-cqlsh-version.adoc b/modules/commands/pages/astra-db-cqlsh-version.adoc new file mode 100644 index 0000000..5255698 --- /dev/null +++ b/modules/commands/pages/astra-db-cqlsh-version.adoc @@ -0,0 +1,55 @@ += astra db cqlsh version + +[source,shell] +---- +astra db cqlsh version [-qV] [--debug] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] + [--connect-timeout=TIMEOUT] [--encoding=ENCODING] + [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN + [--env=ENV]]] + +---- + + +Display the currently installed cqlsh's version + + + + + +== Options + +`--debug`:: Show additional debugging information +`--encoding`:: Output encoding (default: utf8) +`--connect-timeout`:: Connection timeout in seconds + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Display cqlsh's version information +$ astra db cqlsh version +---- + + diff --git a/modules/commands/pages/astra-db-cqlsh.adoc b/modules/commands/pages/astra-db-cqlsh.adoc new file mode 100644 index 0000000..b439a0e --- /dev/null +++ b/modules/commands/pages/astra-db-cqlsh.adoc @@ -0,0 +1,42 @@ += astra db cqlsh + +[source,shell] +---- +astra db cqlsh [COMMAND] + +---- + + +Connect to your Astra database using cqlsh + + + +== Subcommands + +* xref:astra-db-cqlsh-start.adoc[astra db cqlsh start] +* xref:astra-db-cqlsh-exec.adoc[astra db cqlsh exec] +* xref:astra-db-cqlsh-version.adoc[astra db cqlsh version] +* xref:astra-db-cqlsh-path.adoc[astra db cqlsh path] + + +== Options + + + +== Examples +[source,bash] +---- +# Launch cqlsh for a database +$ astra db cqlsh start my_db + +# Launch cqlsh with a specific keyspace +$ astra db cqlsh start my_db -k my_keyspace + +# Execute a CQL statement +$ astra db cqlsh exec my_db "SELECT * FROM my_keyspace.my_table" + +# Execute a CQL file +$ astra db cqlsh exec my_db -f script.cql +---- + + diff --git a/modules/commands/pages/astra-db-create-cdc.adoc b/modules/commands/pages/astra-db-create-cdc.adoc new file mode 100644 index 0000000..4920ef1 --- /dev/null +++ b/modules/commands/pages/astra-db-create-cdc.adoc @@ -0,0 +1,64 @@ += astra db create-cdc + +[source,shell] +---- +astra db create-cdc [-qV] [--if-not-exists] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] [-k=KEYSPACE] + [-o=FORMAT] --table=TABLE --tenant=TENANT + [--topic-partitions=PARTITIONS] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +Create a CDC (Change Data Capture) for a table in a specific keyspace and tenant. + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: Keyspace where the table resides +`--table`:: The table or collection to create CDC for +`--tenant`:: The tenant name +`--topic-partitions`:: Number of topic partitions +`--if-not-exists`:: Will create a new CDC only if none exists + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Create a CDC +$ astra db create-cdc my_db --table my_table --tenant my_tenant + +# Create a CDC with a specific keyspace and topic partitions +$ astra db create-cdc my_db -k my_keyspace --table my_table --tenant my_tenant --topic-partitions 5 + +# Create a CDC without failing if it already exists +$ astra db create-cdc my_db --table my_table --tenant my_tenant --if-not-exists +---- + + diff --git a/modules/commands/pages/astra-db-create-collection.adoc b/modules/commands/pages/astra-db-create-collection.adoc new file mode 100644 index 0000000..99c62f2 --- /dev/null +++ b/modules/commands/pages/astra-db-create-collection.adoc @@ -0,0 +1,80 @@ += astra db create-collection + +[source,shell] +---- +astra db create-collection [-qV] [--if-not-exists] [--no-input] [--[no-] + spinner] [--dump-logs[=FILE]] -c=COLLECTION + [--color=WHEN] [-d=DIMENSION] + [--default-id=DEFAULT_ID] + [--embedding-key=EMBEDDING_KEY] + [--embedding-model=EMBEDDING_MODEL] + [--embedding-provider=EMBEDDING_PROVIDER] + [-k=KEYSPACE] [-m=METRIC] [-o=FORMAT] + [--indexing-allow=INDEXING_ALLOW[, + INDEXING_ALLOW...]]... [--indexing-deny=INDEXING_DENY + [,INDEXING_DENY...]]... [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +Create a new Data API collection in the specified database and keyspace + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: The keyspace to use +`-c`, `--collection`:: The collection to use +`--if-not-exists`:: Will create a new collection only if none with same name +`-d`, `--dimension`:: Dimension of the vector space for this collection +`--default-id`:: Default identifier to use for the collection +`-m`, `--metric`:: Distance metric to use for vector similarity searches +`--indexing-allow`:: List of attributes to add into index (comma separated) +`--indexing-deny`:: List of attributes to remove from index (comma separated) +`--embedding-provider`:: Using Vectorize, embedding provider to use +`--embedding-model`:: Using Vectorize, embedding model to use +`--embedding-key`:: Using Vectorize, embedding key used for shared secret + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Create a basic collection +$ astra db create-collection my_db -c my_collection + +# Create a vector collection +$ astra db create-collection my_db -c my_collection --dimension 2048 + +# Create a collection in a non-default keyspace +$ astra db create-collection my_db -k my_keyspace -c my_collection + +# Create a collection without failing if it already exists +$ astra db create-collection my_db -c my_collection --if-not-exists +---- + + diff --git a/modules/commands/pages/astra-db-create-dotenv.adoc b/modules/commands/pages/astra-db-create-dotenv.adoc new file mode 100644 index 0000000..bc4d58d --- /dev/null +++ b/modules/commands/pages/astra-db-create-dotenv.adoc @@ -0,0 +1,77 @@ += astra db create-dotenv + +[source,shell] +---- +astra db create-dotenv [-qV] [--no-input] [--[no-]overwrite] [--print] [--[no-] + spinner] [--dump-logs[=FILE]] [--color=WHEN] + [--file=FILE] [-k=KEYSPACE] [-o=FORMAT] [-r=REGION] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + [--keys=KEYS[,KEYS...] [--keys=KEYS[,KEYS...]]... | + --preset=PRESETS[,PRESETS...] [--preset=PRESETS[, + PRESETS...]]...] [DB] + +---- + + +Create a env file to help you connect to your Astra DB instance. + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`--print`:: Output the .env file to stdout instead of saving it to the .env file. +`--overwrite`:: Whether to existing duplicate keys in the .env file. If false, the command will attempt to prompt the user before overwriting any existing keys, or fail if it can't. +`--file`:: The file to append the .env content to. If not specified, defaults to .env. If --print is true, the --file option will be used as the initial content; otherwise it will print a new .env file. +`-k`, `--keyspace`:: The keyspace to use. Uses the db's default keyspace if not specified. +`-r`, `--region`:: The region to use. Uses the db's default region if not specified. +`--keys`:: Comma-separated list of keys to include in the .env file. If not specified, all keys will be included. +`--preset`:: The preset(s) to use for the .env file. If not specified, all keys (or the keys from `--keys`) will be used. + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Create a fully-populated .env file, updating the existing one if it exists +$ astra db create-dotenv + +# Create a .env file specifying the keys to include +$ astra db create-dotenv --keys ASTRA_DB_APPLICATION_TOKEN,ASTRA_DB_API_ENDPOINT + +# Create a .env file with a preset specifying the keys to include +$ astra db create-dotenv --preset data_api_client + +# Create a .env file specifying the keyspace and/or region to target +$ astra db create-dotenv -k my_keyspace -r us-east1 + +# Print the .env file to stdout instead of saving it to a file +$ astra db create-dotenv --print + +# Specify the file to create/update +$ astra db create-dotenv -f .env.local +---- + + diff --git a/modules/commands/pages/astra-db-create-keyspace.adoc b/modules/commands/pages/astra-db-create-keyspace.adoc new file mode 100644 index 0000000..21f2aa6 --- /dev/null +++ b/modules/commands/pages/astra-db-create-keyspace.adoc @@ -0,0 +1,63 @@ += astra db create-keyspace + +[source,shell] +---- +astra db create-keyspace [-qV] [--[no-]async] [--if-not-exists] [--no-input] [-- + [no-]spinner] [--dump-logs[=FILE]] [--color=WHEN] + -k=KEYSPACE [-o=FORMAT] [--timeout=] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + [DB] + +---- + + +Create a new keyspace in the specified database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: The keyspace to use +`--if-not-exists`:: Don't error if a keyspace with the same name already exists +`--async`:: Do not wait for the database to become active +`--timeout`:: How long the command should wait for the database to become active + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Create a new keyspace +$ astra db create-keyspace my_db -k my_keyspace + +# Create a new keyspace without failing if it already exists +$ astra db create-keyspace my_db -k my_keyspace --if-not-exists + +# Create a new keyspace without waiting for the database to become active +$ astra db create-keyspace my_db -k my_keyspace --async +---- + + diff --git a/modules/commands/pages/astra-db-create-region.adoc b/modules/commands/pages/astra-db-create-region.adoc new file mode 100644 index 0000000..57ed657 --- /dev/null +++ b/modules/commands/pages/astra-db-create-region.adoc @@ -0,0 +1,62 @@ += astra db create-region + +[source,shell] +---- +astra db create-region [-qV] [--[no-]async] [--if-not-exists] [--no-input] [-- + [no-]spinner] [--dump-logs[=FILE]] [--color=WHEN] + [-o=FORMAT] -r=REGION [--timeout=] [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] DB + +---- + + +Add a new region to an existing database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-r`, `--region`:: The region to use +`--async`:: Do not wait for the database to become active +`--if-not-exists`:: Do not fail if the region already exists +`--timeout`:: How long the command should wait for the database to become active + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Create a region in a database +$ astra db create-region my_db -r us-west-2 + +# Create a region without failing if it already exists +$ astra db create-region my_db -r us-west-2 --if-not-exists + +# Create a region without waiting for the database to become active +$ astra db create-region my_db -r us-west-2 --async +---- + + diff --git a/modules/commands/pages/astra-db-create.adoc b/modules/commands/pages/astra-db-create.adoc new file mode 100644 index 0000000..6004e4d --- /dev/null +++ b/modules/commands/pages/astra-db-create.adoc @@ -0,0 +1,79 @@ += astra db create + +[source,shell] +---- +astra db create [-qV] [--[no-]async] [--no-input] [--non-vector] [--[no-] + spinner] [--dump-logs[=FILE]] [-c=CLOUD] + [--capacity-units=CAPACITY UNITS] [--color=WHEN] [-k=KEYSPACE] + [-o=FORMAT] [-r=REGION] [--tier=TIER] [--timeout=] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + [--if-not-exists | --allow-duplicate-names] DB + +---- + + +Create a new Astra database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`--async`:: Do not wait for the database to become active +`--timeout`:: How long the command should wait for the database to become active +`--if-not-exists`:: Don't error if the database already exists +`--allow-duplicate-names`:: Allow multiple databases with the same name +`-r`, `--region`:: Cloud provider region to provision. **Use one of the `astra db list-regions-*` commands to see available regions.** +`-c`, `--cloud`:: The cloud provider where the db should be created. Inferred from the region if not provided. +`-k`, `--keyspace`:: Default keyspace for the database +`--tier`:: Tier to create the database in +`--capacity-units`:: Capacity units to create the database with +`--non-vector`:: Create a classic non-vector database + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Create a basic Astra vector database in the 'us-east1' region +$ astra db create my_db --region us-east1 + +# Specify a specific default keyspace for the database +$ astra db create my_db --region us-east1 -k my_keyspace + +# Create a classic non-vector database +$ astra db create my_db --region us-east1 --non-vector + +# Create a database without waiting for it to become active +$ astra db create my_db --async + +# Create a database if it doesn't already exist +$ astra db create my_db --region us-east1 --if-not-exists + +# List available vector database regions for creating a database +$ astra db list-regions-vector +---- + + diff --git a/modules/commands/pages/astra-db-delete-cdc.adoc b/modules/commands/pages/astra-db-delete-cdc.adoc new file mode 100644 index 0000000..9dd1e57 --- /dev/null +++ b/modules/commands/pages/astra-db-delete-cdc.adoc @@ -0,0 +1,64 @@ += astra db delete-cdc + +[source,shell] +---- +astra db delete-cdc [-qV] [--if-exists] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + (--cdc-id=CDC_ID | [-k=KEYSPACE --table=TABLE + --tenant=TENANT]) [DB] + +---- + + +Delete a CDC (Change Data Capture) from the database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`--if-exists`:: Do not fail if CDC does not exist +`--cdc-id`:: The CDC ID to delete +`-k`, `--keyspace`:: The keyspace +`--table`:: The table +`--tenant`:: The tenant name + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Delete a CDC by ID +$ astra db delete-cdc my_db --cdc-id abc123 + +# Delete a CDC by table and tenant +$ astra db delete-cdc my_db -k my_keyspace --table my_table --tenant my_tenant + +# Delete a CDC without failing if it doesn't exist +$ astra db delete-cdc my_db --cdc-id abc123 --if-exists +---- + + diff --git a/modules/commands/pages/astra-db-delete-collection.adoc b/modules/commands/pages/astra-db-delete-collection.adoc new file mode 100644 index 0000000..b357bb6 --- /dev/null +++ b/modules/commands/pages/astra-db-delete-collection.adoc @@ -0,0 +1,61 @@ += astra db delete-collection + +[source,shell] +---- +astra db delete-collection [-qV] [--if-exists] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [-c=COLLECTION] [--color=WHEN] + [-k=KEYSPACE] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +Delete an existing Data API collection from the specified database and keyspace + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: The keyspace to use +`-c`, `--collection`:: The collection to use +`--if-exists`:: Do not fail if collection does not exist + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Delete a collection +$ astra db delete-collection my_db -c my_collection + +# Delete a collection from a non-default keyspace +$ astra db delete-collection my_db -k my_keyspace -c my_collection + +# Delete a collection without failing if it doesn't exist +$ astra db delete-collection my_db -c my_collection --if-exists +---- + + diff --git a/modules/commands/pages/astra-db-delete-keyspace.adoc b/modules/commands/pages/astra-db-delete-keyspace.adoc new file mode 100644 index 0000000..a99235f --- /dev/null +++ b/modules/commands/pages/astra-db-delete-keyspace.adoc @@ -0,0 +1,63 @@ += astra db delete-keyspace + +[source,shell] +---- +astra db delete-keyspace [-qV] [--[no-]async] [--if-exists] [--no-input] [-- + [no-]spinner] [--dump-logs[=FILE]] [--color=WHEN] + [-k=KEYSPACE] [-o=FORMAT] [--timeout=] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + [DB] + +---- + + +Delete a keyspace from the specified database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: The keyspace to use +`--if-exists`:: Do not fail if keyspace does not exist +`--async`:: Do not wait for the database to become active +`--timeout`:: How long the command should wait for the database to become active + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Delete a keyspace +$ astra db delete-keyspace my_db -k my_keyspace + +# Delete a keyspace without failing if it doesn't exist +$ astra db delete-keyspace my_db -k my_keyspace --if-exists + +# Delete a keyspace without waiting for the database to become active +$ astra db delete-keyspace my_db -k my_keyspace --async +---- + + diff --git a/modules/commands/pages/astra-db-delete-region.adoc b/modules/commands/pages/astra-db-delete-region.adoc new file mode 100644 index 0000000..557195f --- /dev/null +++ b/modules/commands/pages/astra-db-delete-region.adoc @@ -0,0 +1,62 @@ += astra db delete-region + +[source,shell] +---- +astra db delete-region [-qV] [--[no-]async] [--if-exists] [--no-input] [--[no-] + spinner] [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] + -r=REGION [--timeout=] [[[-cf=PATH] [-p=NAME]] + | [--token=TOKEN [--env=ENV]]] DB + +---- + + +Delete a region from an existing database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-r`, `--region`:: The region to use +`--async`:: Do not wait for the database to become active +`--if-exists`:: Do not fail if region does not exist +`--timeout`:: How long the command should wait for the database to become active + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Delete a region from a database +$ astra db delete-region my_db -r us-west-2 + +# Delete a region without failing if it doesn't exist +$ astra db delete-region my_db -r us-west-2 --if-exists + +# Delete a region without waiting for the database to become active +$ astra db delete-region my_db -r us-west-2 --async +---- + + diff --git a/modules/commands/pages/astra-db-delete-table.adoc b/modules/commands/pages/astra-db-delete-table.adoc new file mode 100644 index 0000000..b893560 --- /dev/null +++ b/modules/commands/pages/astra-db-delete-table.adoc @@ -0,0 +1,61 @@ += astra db delete-table + +[source,shell] +---- +astra db delete-table [-qV] [--if-exists] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] [-k=KEYSPACE] + [-o=FORMAT] [-t=TABLE] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +Delete an existing table from the specified database and keyspace + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: The keyspace to use +`-t`, `--table`:: The table to use +`--if-exists`:: Do not fail if table does not exist + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Delete a table +$ astra db delete-table my_db -t my_table + +# Delete a table from a non-default keyspace +$ astra db delete-table my_db -k my_keyspace -t my_table + +# Delete a table without failing if it doesn't exist +$ astra db delete-table my_db -t my_table --if-exists +---- + + diff --git a/modules/commands/pages/astra-db-delete.adoc b/modules/commands/pages/astra-db-delete.adoc new file mode 100644 index 0000000..58b91ee --- /dev/null +++ b/modules/commands/pages/astra-db-delete.adoc @@ -0,0 +1,65 @@ += astra db delete + +[source,shell] +---- +astra db delete [-qV] [--[no-]async] [--if-exists] [--no-input] [--[no-] + spinner] [--yes] [--dump-logs[=FILE]] [--color=WHEN] + [-o=FORMAT] [--timeout=] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +Delete an existing Astra database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`--if-exists`:: Do not fail if database does not exist +`--yes`:: Force deletion of database without prompting +`--async`:: Do not wait for the database to become active +`--timeout`:: How long the command should wait for the database to become active + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Delete an existing Astra database +$ astra db delete my_db + +# Delete an existing Astra database without confirmation (required for non-interactive shells) +$ astra db delete my_db --yes + +# Delete an existing Astra database without failing if it does not exist +$ astra db delete my_db --if-exists + +# Delete an existing Astra database without waiting for complete termination +$ astra db delete my_db --async +---- + + diff --git a/modules/commands/pages/astra-db-describe-collection.adoc b/modules/commands/pages/astra-db-describe-collection.adoc new file mode 100644 index 0000000..6b5ba7e --- /dev/null +++ b/modules/commands/pages/astra-db-describe-collection.adoc @@ -0,0 +1,57 @@ += astra db describe-collection + +[source,shell] +---- +astra db describe-collection [-qV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [-c=COLLECTION] [--color=WHEN] + [-k=KEYSPACE] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] + | [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +Describe an existing Data API collection with detailed information including vector configuration and indexing options + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: The keyspace to use +`-c`, `--collection`:: The collection to use + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Describe a collection in the default keyspace +$ astra db describe-collection my_db -c my_collection + +# Describe a collection in a specific keyspace +$ astra db describe-collection my_db -k my_keyspace -c my_collection +---- + + diff --git a/modules/commands/pages/astra-db-describe-table.adoc b/modules/commands/pages/astra-db-describe-table.adoc new file mode 100644 index 0000000..28981c1 --- /dev/null +++ b/modules/commands/pages/astra-db-describe-table.adoc @@ -0,0 +1,57 @@ += astra db describe-table + +[source,shell] +---- +astra db describe-table [-qV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-k=KEYSPACE] [-o=FORMAT] + [-t=TABLE] [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN + [--env=ENV]]] [DB] + +---- + + +Describe an existing table with detailed information including columns and primary key structure + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: The keyspace to use +`-t`, `--table`:: The table to use + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Describe a table in the default keyspace +$ astra db describe-table my_db -t my_table + +# Describe a table in a specific keyspace +$ astra db describe-table my_db -k my_keyspace -t my_table +---- + + diff --git a/modules/commands/pages/astra-db-download-scb.adoc b/modules/commands/pages/astra-db-download-scb.adoc new file mode 100644 index 0000000..bee6693 --- /dev/null +++ b/modules/commands/pages/astra-db-download-scb.adoc @@ -0,0 +1,60 @@ += astra db download-scb + +[source,shell] +---- +astra db download-scb [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-f=DEST] [-o=FORMAT] [-r=REGION] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + [DB] + +---- + + +Download secure connect bundle for a database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-r`, `--region`:: The cloud provider region to target. Defaults to the default region of the database. +`-f`, `--file`:: Destination file. Defaults to `~/.astra/scb/scb__.zip` + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Download the SCB for a database, targeting the default region +$ astra db download-scb my_db + +# Download the SCB for a database, targeting a specific region +$ astra db download-scb my_db -r us-east1 + +# Download the SCB for a database, saving it to a specific file +$ astra db download-scb my_db -f /path/to/scb.zip +---- + + diff --git a/modules/commands/pages/astra-db-dsbulk-count.adoc b/modules/commands/pages/astra-db-dsbulk-count.adoc new file mode 100644 index 0000000..8162701 --- /dev/null +++ b/modules/commands/pages/astra-db-dsbulk-count.adoc @@ -0,0 +1,63 @@ += astra db dsbulk count + +[source,shell] +---- +astra db dsbulk count [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [--encoding=ENCODING] [-k=KEYSPACE] + [--log-dir=DIRECTORY] [--max-concurrent-queries=QUERIES] + [-o=FORMAT] [-query=QUERY] [-r=REGION] [-t=TABLE] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + [--dsbulk-config=CONFIG_FILE | -F=FLAGS [-F=FLAGS]...] + [DB] + +---- + + +Count items for a table, a query + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: Keyspace used for loading or unloading data +`-t`, `--table`:: Table used for loading or unloading data. +`--encoding`:: The file name format to use when writing. This setting is ignored when reading and for non-file URLs +`--max-concurrent-queries`:: The maximum number of concurrent queries that should be carried in parallel +`--log-dir`:: Log directory for dsbulk operations +`-r`, `--region`:: The region to use. Uses the db's default region if not specified. +`-query`, `--schema.query`:: Optional query to unload or count +`--dsbulk-config`:: Configuration file for DSBulk loader options +`-F`, `--dsbulk-flags`:: Additional flags to pass to DSBulk loader + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- + +---- + + diff --git a/modules/commands/pages/astra-db-dsbulk-load.adoc b/modules/commands/pages/astra-db-dsbulk-load.adoc new file mode 100644 index 0000000..d933826 --- /dev/null +++ b/modules/commands/pages/astra-db-dsbulk-load.adoc @@ -0,0 +1,72 @@ += astra db dsbulk load + +[source,shell] +---- +astra db dsbulk load [-qV] [--allow-missing-fields] [--dry-run] [--header] + [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [--delimiter=DELIMITER] + [--encoding=ENCODING] [-k=KEYSPACE] [--log-dir=DIRECTORY] + [-m=MAPPING] [--max-concurrent-queries=QUERIES] + [--max-errors=COUNT] [-o=FORMAT] [-r=REGION] + [--skip-records=COUNT] [-t=TABLE] --url=URL [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + [--dsbulk-config=CONFIG_FILE | -F=FLAGS [-F=FLAGS]...] [DB] + +---- + + +Load data leveraging DSBulk + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: Keyspace used for loading or unloading data +`-t`, `--table`:: Table used for loading or unloading data. +`--encoding`:: The file name format to use when writing. This setting is ignored when reading and for non-file URLs +`--max-concurrent-queries`:: The maximum number of concurrent queries that should be carried in parallel +`--log-dir`:: Log directory for dsbulk operations +`-r`, `--region`:: The region to use. Uses the db's default region if not specified. +`--url`:: File location to load data +`--delimiter`:: Character(s) use as field delimiter +`-m`, `--schema.mapping`:: Field-to-column mapping to use +`--header`:: Read, Write Header in input file +`--skip-records`:: Lines to skip before reading +`--max-errors`:: Maximum number of errors before aborting the operation +`--dry-run`:: Enable or disable dry-run mode +`--allow-missing-fields`:: Ease the mapping +`--dsbulk-config`:: Configuration file for DSBulk loader options +`-F`, `--dsbulk-flags`:: Additional flags to pass to DSBulk loader + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- + +---- + + diff --git a/modules/commands/pages/astra-db-dsbulk-path.adoc b/modules/commands/pages/astra-db-dsbulk-path.adoc new file mode 100644 index 0000000..9363e03 --- /dev/null +++ b/modules/commands/pages/astra-db-dsbulk-path.adoc @@ -0,0 +1,57 @@ += astra db dsbulk path + +[source,shell] +---- +astra db dsbulk path [-qV] [--if-exists] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + +---- + + +Get the path to the currently installed dsbulk executable + + + + + +== Options + +`--if-exists`:: Only return path if dsbulk exists, don't install automatically + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Get the path to the dsbulk executable +$ astra db dsbulk path + +# Use the dsbulk exe to run a custom command +$ $(astra db dsbulk path) --help + +# Get path only if dsbulk exists, don't install +$ astra db dsbulk path --if-exists +---- + + diff --git a/modules/commands/pages/astra-db-dsbulk-unload.adoc b/modules/commands/pages/astra-db-dsbulk-unload.adoc new file mode 100644 index 0000000..4da1871 --- /dev/null +++ b/modules/commands/pages/astra-db-dsbulk-unload.adoc @@ -0,0 +1,72 @@ += astra db dsbulk unload + +[source,shell] +---- +astra db dsbulk unload [-qV] [--header] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] + [--delimiter=DELIMITER] [--encoding=ENCODING] + [-k=KEYSPACE] [--log-dir=DIRECTORY] [-m=MAPPING] + [--max-concurrent-queries=QUERIES] [--max-errors=COUNT] + [-o=FORMAT] [-query=QUERY] [-r=REGION] + [--skip-records=COUNT] [-t=TABLE] [--url=URL] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + [--dsbulk-config=CONFIG_FILE | -F=FLAGS [-F=FLAGS]...] + [DB] + +---- + + +Unload data leveraging DSBulk + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: Keyspace used for loading or unloading data +`-t`, `--table`:: Table used for loading or unloading data. +`--encoding`:: The file name format to use when writing. This setting is ignored when reading and for non-file URLs +`--max-concurrent-queries`:: The maximum number of concurrent queries that should be carried in parallel +`--log-dir`:: Log directory for dsbulk operations +`-r`, `--region`:: The region to use. Uses the db's default region if not specified. +`--url`:: The URL or path of the resource(s) to read from or write to +`--delimiter`:: Character(s) use as field delimiter +`-m`, `--schema.mapping`:: Field-to-column mapping to use +`--header`:: Enable or disable whether the files begin with a header line +`--skip-records`:: Number of records to skip from each input file before parsing +`--max-errors`:: Maximum number of errors to tolerate before aborting the operation +`-query`, `--schema.query`:: Optional query to unload or count +`--dsbulk-config`:: Configuration file for DSBulk loader options +`-F`, `--dsbulk-flags`:: Additional flags to pass to DSBulk loader + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- + +---- + + diff --git a/modules/commands/pages/astra-db-dsbulk-version.adoc b/modules/commands/pages/astra-db-dsbulk-version.adoc new file mode 100644 index 0000000..6f3c7ec --- /dev/null +++ b/modules/commands/pages/astra-db-dsbulk-version.adoc @@ -0,0 +1,50 @@ += astra db dsbulk version + +[source,shell] +---- +astra db dsbulk version [-qV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + +---- + + +Display the currently installed dsbulk's version + + + + + +== Options + + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Display dsbulk's version information +$ astra db dsbulk version +---- + + diff --git a/modules/commands/pages/astra-db-dsbulk.adoc b/modules/commands/pages/astra-db-dsbulk.adoc new file mode 100644 index 0000000..82df9fc --- /dev/null +++ b/modules/commands/pages/astra-db-dsbulk.adoc @@ -0,0 +1,33 @@ += astra db dsbulk + +[source,shell] +---- +astra db dsbulk [COMMAND] + +---- + + +Use dsbulk to interface with your Astra DB database + + + +== Subcommands + +* xref:astra-db-dsbulk-count.adoc[astra db dsbulk count] +* xref:astra-db-dsbulk-load.adoc[astra db dsbulk load] +* xref:astra-db-dsbulk-unload.adoc[astra db dsbulk unload] +* xref:astra-db-dsbulk-version.adoc[astra db dsbulk version] +* xref:astra-db-dsbulk-path.adoc[astra db dsbulk path] + + +== Options + + + +== Examples +[source,bash] +---- + +---- + + diff --git a/modules/commands/pages/astra-db-get-endpoint-api.adoc b/modules/commands/pages/astra-db-get-endpoint-api.adoc new file mode 100644 index 0000000..9445926 --- /dev/null +++ b/modules/commands/pages/astra-db-get-endpoint-api.adoc @@ -0,0 +1,56 @@ += astra db get-endpoint-api + +[source,shell] +---- +astra db get-endpoint-api [-qV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [-r=REGION] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN + [--env=ENV]]] [DB] + +---- + + +Get the API endpoint to interact with the specified database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-r`, `--region`:: The region to use + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Get the API endpoint for the database +$ astra db get-endpoint-api mydb + +# Get the API endpoint for the database in a specific region +$ astra db get-endpoint-api mydb --region us-east1 +---- + + diff --git a/modules/commands/pages/astra-db-get-endpoint-playground.adoc b/modules/commands/pages/astra-db-get-endpoint-playground.adoc new file mode 100644 index 0000000..0d6f18e --- /dev/null +++ b/modules/commands/pages/astra-db-get-endpoint-playground.adoc @@ -0,0 +1,56 @@ += astra db get-endpoint-playground + +[source,shell] +---- +astra db get-endpoint-playground [-qV] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] + [-o=FORMAT] [-r=REGION] [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +Get the GraphQL Playground for the specified database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-r`, `--region`:: The region to use + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Get the GraphQL Playground for the database +$ astra db get-endpoint-playground mydb + +# Get the GraphQL Playground for the database in a specific region +$ astra db get-endpoint-playground mydb --region us-east1 +---- + + diff --git a/modules/commands/pages/astra-db-get-endpoint-swagger.adoc b/modules/commands/pages/astra-db-get-endpoint-swagger.adoc new file mode 100644 index 0000000..d2f9260 --- /dev/null +++ b/modules/commands/pages/astra-db-get-endpoint-swagger.adoc @@ -0,0 +1,56 @@ += astra db get-endpoint-swagger + +[source,shell] +---- +astra db get-endpoint-swagger [-qV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [-r=REGION] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN + [--env=ENV]]] [DB] + +---- + + +Get the SwaggerUI endpoint for the specified database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-r`, `--region`:: The region to use + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Get the SwaggerUI endpoint for the database +$ astra db get-endpoint-swagger mydb + +# Get the SwaggerUI endpoint for the database in a specific region +$ astra db get-endpoint-swagger mydb --region us-east1 +---- + + diff --git a/modules/commands/pages/astra-db-get.adoc b/modules/commands/pages/astra-db-get.adoc new file mode 100644 index 0000000..913e553 --- /dev/null +++ b/modules/commands/pages/astra-db-get.adoc @@ -0,0 +1,58 @@ += astra db get + +[source,shell] +---- +astra db get [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-k=KEY] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +Get information about a specific database. + +== Aliases + +`astra db describe` + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--key`:: Specific database attribute to retrieve + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Get information about a specific database +$ astra db get my_db + +# Get a specific attribute of a database +$ astra db get my_db --key id +---- + + diff --git a/modules/commands/pages/astra-db-list-cdcs.adoc b/modules/commands/pages/astra-db-list-cdcs.adoc new file mode 100644 index 0000000..26c39c9 --- /dev/null +++ b/modules/commands/pages/astra-db-list-cdcs.adoc @@ -0,0 +1,51 @@ += astra db list-cdcs + +[source,shell] +---- +astra db list-cdcs [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +List all CDC (Change Data Capture) connections for the specified database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# List all CDCs in a database +$ astra db list-cdcs my_db +---- + + diff --git a/modules/commands/pages/astra-db-list-clouds.adoc b/modules/commands/pages/astra-db-list-clouds.adoc new file mode 100644 index 0000000..2b7f336 --- /dev/null +++ b/modules/commands/pages/astra-db-list-clouds.adoc @@ -0,0 +1,50 @@ += astra db list-clouds + +[source,shell] +---- +astra db list-clouds [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] + +---- + + +List all cloud providers with regions available for Astra DB + + + + + +== Options + + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# List all available cloud providers +$ astra db list-clouds +---- + + diff --git a/modules/commands/pages/astra-db-list-collections.adoc b/modules/commands/pages/astra-db-list-collections.adoc new file mode 100644 index 0000000..13badf9 --- /dev/null +++ b/modules/commands/pages/astra-db-list-collections.adoc @@ -0,0 +1,60 @@ += astra db list-collections + +[source,shell] +---- +astra db list-collections [-aqV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-k=KEYSPACE] [-o=FORMAT] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN + [--env=ENV]]] [DB] + +---- + + +List the collections in the specified database and keyspace + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: The keyspace to use +`-a`, `--all`:: List collections in all keyspaces + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# List all collections in the default keyspace +$ astra db list-collections my_db + +# List all collections in a specific keyspace +$ astra db list-collections my_db -k my_keyspace + +# List all collections in all keyspaces +$ astra db list-collections my_db --all +---- + + diff --git a/modules/commands/pages/astra-db-list-embedding-providers.adoc b/modules/commands/pages/astra-db-list-embedding-providers.adoc new file mode 100644 index 0000000..a226bed --- /dev/null +++ b/modules/commands/pages/astra-db-list-embedding-providers.adoc @@ -0,0 +1,52 @@ += astra db list-embedding-providers + +[source,shell] +---- +astra db list-embedding-providers [-qV] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] + [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +Find all available embedding providers for a given database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Find all available embedding providers for a database +$ astra db list-embedding-providers my_db +---- + + diff --git a/modules/commands/pages/astra-db-list-keyspaces.adoc b/modules/commands/pages/astra-db-list-keyspaces.adoc new file mode 100644 index 0000000..deb5117 --- /dev/null +++ b/modules/commands/pages/astra-db-list-keyspaces.adoc @@ -0,0 +1,51 @@ += astra db list-keyspaces + +[source,shell] +---- +astra db list-keyspaces [-qV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +List all keyspaces in the specified database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# List all keyspaces in a database +$ astra db list-keyspaces my_db +---- + + diff --git a/modules/commands/pages/astra-db-list-regions-classic.adoc b/modules/commands/pages/astra-db-list-regions-classic.adoc new file mode 100644 index 0000000..548c226 --- /dev/null +++ b/modules/commands/pages/astra-db-list-regions-classic.adoc @@ -0,0 +1,64 @@ += astra db list-regions-classic + +[source,shell] +---- +astra db list-regions-classic [-qV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [-c=FILTER[, + FILTER...]]... [-f=FILTER[,FILTER...]]... + [-z=FILTER[,FILTER...]]... [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + +---- + + +List all available regions for classic Astra DB databases + + + + + +== Options + +`-f`, `--filter`:: Comma-separated case-insensitive partial-match filters on the region name +`-c`, `--cloud`:: Comma-separated list of cloud providers to filter on +`-z`, `--zone`:: Comma-separated list of zones to include + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# List all available regions for classic Astra DB databases +$ astra db list-regions-classic + +# Filter by cloud provider +$ astra db list-regions-classic --cloud AWS,GCP + +# Filter by partial region name +$ astra db list-regions-classic --filter us-,ca- + +# Filter by zone +$ astra db list-regions-classic --zone Europe +---- + + diff --git a/modules/commands/pages/astra-db-list-regions-serverless.adoc b/modules/commands/pages/astra-db-list-regions-serverless.adoc new file mode 100644 index 0000000..a035ed1 --- /dev/null +++ b/modules/commands/pages/astra-db-list-regions-serverless.adoc @@ -0,0 +1,65 @@ += astra db list-regions-serverless + +[source,shell] +---- +astra db list-regions-serverless [-qV] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] + [-o=FORMAT] [-c=FILTER[,FILTER...]]... + [-f=FILTER[,FILTER...]]... [-z=FILTER[, + FILTER...]]... [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] + +---- + + +List all available regions for serverless Astra DB databases + + + + + +== Options + +`-f`, `--filter`:: Comma-separated case-insensitive partial-match filters on the region name +`-c`, `--cloud`:: Comma-separated list of cloud providers to filter on +`-z`, `--zone`:: Comma-separated list of zones to include + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# List all available regions for serverless Astra DB databases +$ astra db list-regions-serverless + +# Filter by cloud provider +$ astra db list-regions-serverless --cloud AWS,GCP + +# Filter by partial region name +$ astra db list-regions-serverless --filter us-,ca- + +# Filter by zone +$ astra db list-regions-serverless --zone Europe +---- + + diff --git a/modules/commands/pages/astra-db-list-regions-vector.adoc b/modules/commands/pages/astra-db-list-regions-vector.adoc new file mode 100644 index 0000000..fd64863 --- /dev/null +++ b/modules/commands/pages/astra-db-list-regions-vector.adoc @@ -0,0 +1,64 @@ += astra db list-regions-vector + +[source,shell] +---- +astra db list-regions-vector [-qV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [-c=FILTER[, + FILTER...]]... [-f=FILTER[,FILTER...]]... + [-z=FILTER[,FILTER...]]... [[[-cf=PATH] [-p=NAME]] + | [--token=TOKEN [--env=ENV]]] + +---- + + +List all available regions for vector Astra DB databases + + + + + +== Options + +`-f`, `--filter`:: Comma-separated case-insensitive partial-match filters on the region name +`-c`, `--cloud`:: Comma-separated list of cloud providers to filter on +`-z`, `--zone`:: Comma-separated list of zones to include + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# List all available regions for vector Astra DB databases +$ astra db list-regions-vector + +# Filter by cloud provider +$ astra db list-regions-vector --cloud AWS,GCP + +# Filter by partial region name +$ astra db list-regions-vector --filter us-,ca- + +# Filter by zone +$ astra db list-regions-vector --zone Europe +---- + + diff --git a/modules/commands/pages/astra-db-list-regions.adoc b/modules/commands/pages/astra-db-list-regions.adoc new file mode 100644 index 0000000..0793925 --- /dev/null +++ b/modules/commands/pages/astra-db-list-regions.adoc @@ -0,0 +1,51 @@ += astra db list-regions + +[source,shell] +---- +astra db list-regions [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +List the regions for the given database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# List all regions for the database +$ astra db list-regions my_db +---- + + diff --git a/modules/commands/pages/astra-db-list-tables.adoc b/modules/commands/pages/astra-db-list-tables.adoc new file mode 100644 index 0000000..7fdc2be --- /dev/null +++ b/modules/commands/pages/astra-db-list-tables.adoc @@ -0,0 +1,59 @@ += astra db list-tables + +[source,shell] +---- +astra db list-tables [-aqV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-k=KEYSPACE] [-o=FORMAT] [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +List the tables in the specified database and keyspace + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: The keyspace to use +`-a`, `--all`:: List tables in all keyspaces + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# List all tables in the default keyspace +$ astra db list-tables my_db + +# List all tables in a specific keyspace +$ astra db list-tables my_db -k my_keyspace + +# List all tables in all keyspaces +$ astra db list-tables my_db --all +---- + + diff --git a/modules/commands/pages/astra-db-list.adoc b/modules/commands/pages/astra-db-list.adoc new file mode 100644 index 0000000..f85e846 --- /dev/null +++ b/modules/commands/pages/astra-db-list.adoc @@ -0,0 +1,57 @@ += astra db list + +[source,shell] +---- +astra db list [-qvV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] + +---- + + +List your non-terminated Astra databases. + +== Aliases + +`astra db` + + + + +== Options + +`-v`, `--vector`:: Only show vector-enabled databases + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# List all your Astra databases +$ astra db list + +# List only vector-enabled Astra databases +$ astra db list --vector +---- + + diff --git a/modules/commands/pages/astra-db-resume.adoc b/modules/commands/pages/astra-db-resume.adoc new file mode 100644 index 0000000..286d0b5 --- /dev/null +++ b/modules/commands/pages/astra-db-resume.adoc @@ -0,0 +1,56 @@ += astra db resume + +[source,shell] +---- +astra db resume [-qV] [--[no-]async] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [--timeout=] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +Resume a database that is in a stopped state. If the database is already active, no action is taken. + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`--async`:: Do not wait for the database to become active +`--timeout`:: How long the command should wait for the database to become active + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Resume a database +$ astra db resume my_db + +# Resume a database, without waiting for it to become active +$ astra db resume my_db --async +---- + + diff --git a/modules/commands/pages/astra-db-status.adoc b/modules/commands/pages/astra-db-status.adoc new file mode 100644 index 0000000..d2eed35 --- /dev/null +++ b/modules/commands/pages/astra-db-status.adoc @@ -0,0 +1,51 @@ += astra db status + +[source,shell] +---- +astra db status [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +Get the current status of a database. + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Get the status of a database +$ astra db status my_db +---- + + diff --git a/modules/commands/pages/astra-db-truncate-collection.adoc b/modules/commands/pages/astra-db-truncate-collection.adoc new file mode 100644 index 0000000..2273ba5 --- /dev/null +++ b/modules/commands/pages/astra-db-truncate-collection.adoc @@ -0,0 +1,57 @@ += astra db truncate-collection + +[source,shell] +---- +astra db truncate-collection [-qV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [-c=COLLECTION] [--color=WHEN] + [-k=KEYSPACE] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] + | [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +Atomically delete all documents in a Data API collection + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: The keyspace to use +`-c`, `--collection`:: The collection to use + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Truncate a collection in the default keyspace +$ astra db truncate-collection my_db -c my_collection + +# Truncate a collection in a specific keyspace +$ astra db truncate-collection my_db -k my_keyspace -c my_collection +---- + + diff --git a/modules/commands/pages/astra-db-truncate-table.adoc b/modules/commands/pages/astra-db-truncate-table.adoc new file mode 100644 index 0000000..c399f4d --- /dev/null +++ b/modules/commands/pages/astra-db-truncate-table.adoc @@ -0,0 +1,57 @@ += astra db truncate-table + +[source,shell] +---- +astra db truncate-table [-qV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-k=KEYSPACE] [-o=FORMAT] + [-t=TABLE] [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN + [--env=ENV]]] [DB] + +---- + + +Atomically delete all rows in a table + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: The keyspace to use +`-t`, `--table`:: The table to use + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Truncate a table in the default keyspace +$ astra db truncate-table my_db -t my_table + +# Truncate a table in a specific keyspace +$ astra db truncate-table my_db -k my_keyspace -t my_table +---- + + diff --git a/modules/commands/pages/astra-db.adoc b/modules/commands/pages/astra-db.adoc new file mode 100644 index 0000000..0d69a69 --- /dev/null +++ b/modules/commands/pages/astra-db.adoc @@ -0,0 +1,94 @@ += astra db + +[source,shell] +---- +astra db [-qvV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN + [--env=ENV]]] [COMMAND] + +---- + + +Manage your Astra databases + + +**Alias of `astra db list`** + + +== Subcommands + +* xref:astra-db-list.adoc[astra db list] +* xref:astra-db-get.adoc[astra db get] +* xref:astra-db-create.adoc[astra db create] +* xref:astra-db-delete.adoc[astra db delete] +* xref:astra-db-status.adoc[astra db status] +* xref:astra-db-cqlsh.adoc[astra db cqlsh] +* xref:astra-db-dsbulk.adoc[astra db dsbulk] +* xref:astra-db-create-dotenv.adoc[astra db create-dotenv] +* xref:astra-db-download-scb.adoc[astra db download-scb] +* xref:astra-db-resume.adoc[astra db resume] +* xref:astra-db-list-keyspaces.adoc[astra db list-keyspaces] +* xref:astra-db-create-keyspace.adoc[astra db create-keyspace] +* xref:astra-db-delete-keyspace.adoc[astra db delete-keyspace] +* xref:astra-db-list-collections.adoc[astra db list-collections] +* xref:astra-db-create-collection.adoc[astra db create-collection] +* xref:astra-db-describe-collection.adoc[astra db describe-collection] +* xref:astra-db-delete-collection.adoc[astra db delete-collection] +* xref:astra-db-truncate-collection.adoc[astra db truncate-collection] +* xref:astra-db-list-tables.adoc[astra db list-tables] +* xref:astra-db-describe-table.adoc[astra db describe-table] +* xref:astra-db-delete-table.adoc[astra db delete-table] +* xref:astra-db-truncate-table.adoc[astra db truncate-table] +* xref:astra-db-list-embedding-providers.adoc[astra db list-embedding-providers] +* xref:astra-db-list-cdcs.adoc[astra db list-cdcs] +* xref:astra-db-create-cdc.adoc[astra db create-cdc] +* xref:astra-db-delete-cdc.adoc[astra db delete-cdc] +* xref:astra-db-create-region.adoc[astra db create-region] +* xref:astra-db-delete-region.adoc[astra db delete-region] +* xref:astra-db-list-regions.adoc[astra db list-regions] +* xref:astra-db-list-regions-classic.adoc[astra db list-regions-classic] +* xref:astra-db-list-regions-serverless.adoc[astra db list-regions-serverless] +* xref:astra-db-list-regions-vector.adoc[astra db list-regions-vector] +* xref:astra-db-list-clouds.adoc[astra db list-clouds] +* xref:astra-db-get-endpoint-swagger.adoc[astra db get-endpoint-swagger] +* xref:astra-db-get-endpoint-api.adoc[astra db get-endpoint-api] +* xref:astra-db-get-endpoint-playground.adoc[astra db get-endpoint-playground] + + +== Options + +`-v`, `--vector`:: Only show vector-enabled databases + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# List all your Astra databases +$ astra db + +# List only vector-enabled Astra databases +$ astra db --vector +---- + + diff --git a/modules/commands/pages/astra-nuke.adoc b/modules/commands/pages/astra-nuke.adoc new file mode 100644 index 0000000..07218bc --- /dev/null +++ b/modules/commands/pages/astra-nuke.adoc @@ -0,0 +1,64 @@ += astra nuke + +[source,shell] +---- +astra nuke [-qVy] [--dry-run] [--no-input] [--[no-]preserve-astrarc] [--[no-] + spinner] [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] + +---- + + +Entirely delete Astra CLI from your system + +This command may be used to delete any files associated with Astra CLI, including: + + * The ``.astra`` home folder, + + * The ``.astrarc`` file, + + * and the binary itself. + +This will also detect any shell rc files which need ``astra``-related lines removed. + +**Note:** Depending on how Astra CLI was installed, the binary itself may need to be deleted manually. In such cases, instructions will be provided in the command output. + + + + + +== Options + +`--dry-run`:: Simulate the nuke operation without deleting any files +`--preserve-astrarc`:: Preserve the ``.astrarc`` file in your home directory +`-y`, `--yes`:: Whether to nuke without confirmation (if not a dry run) + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + + +== Examples +[source,bash] +---- +# Nuke Astra CLI from your system +$ astra nuke + +# Perform a dry run of the nuke operation +$ astra nuke --dry-run + +# Nuke Astra CLI without confirmation +$ astra nuke --yes + +# Nuke Astra CLI but preserve the ``.astrarc`` file +$ astra nuke --preserve-astrarc +---- + + diff --git a/modules/commands/pages/astra-org-get.adoc b/modules/commands/pages/astra-org-get.adoc new file mode 100644 index 0000000..78bc091 --- /dev/null +++ b/modules/commands/pages/astra-org-get.adoc @@ -0,0 +1,60 @@ += astra org get + +[source,shell] +---- +astra org get [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] + +---- + + +Get your organization's information + +The ``--token`` flag is handy to quickly get information about another organization. + +Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. + +== Aliases + +`astra org` + + + + +== Options + + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Get your organization's information +$ astra org + +# Get information about another organization +$ astra org get --token AstraCS:... +---- + + diff --git a/modules/commands/pages/astra-org-id.adoc b/modules/commands/pages/astra-org-id.adoc new file mode 100644 index 0000000..1b1e89f --- /dev/null +++ b/modules/commands/pages/astra-org-id.adoc @@ -0,0 +1,50 @@ += astra org id + +[source,shell] +---- +astra org id [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] + +---- + + +Get your organization's ID + + + + + +== Options + + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Get your organization's ID +$ astra org id +---- + + diff --git a/modules/commands/pages/astra-org-name.adoc b/modules/commands/pages/astra-org-name.adoc new file mode 100644 index 0000000..5b7d6a1 --- /dev/null +++ b/modules/commands/pages/astra-org-name.adoc @@ -0,0 +1,50 @@ += astra org name + +[source,shell] +---- +astra org name [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] + +---- + + +Get your organization's name + + + + + +== Options + + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Get your organization's name +$ astra org name +---- + + diff --git a/modules/commands/pages/astra-org.adoc b/modules/commands/pages/astra-org.adoc new file mode 100644 index 0000000..76eb898 --- /dev/null +++ b/modules/commands/pages/astra-org.adoc @@ -0,0 +1,64 @@ += astra org + +[source,shell] +---- +astra org [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN + [--env=ENV]]] [COMMAND] + +---- + + +Get organization information + +The ``--token`` flag is handy to quickly get information about another organization. + +Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. + + +**Alias of `astra org get`** + + +== Subcommands + +* xref:astra-org-get.adoc[astra org get] +* xref:astra-org-id.adoc[astra org id] +* xref:astra-org-name.adoc[astra org name] + + +== Options + + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Get your organization's information +$ astra org + +# Get information about another organization +$ astra org get --token AstraCS:... +---- + + diff --git a/modules/commands/pages/astra-pcu-associate.adoc b/modules/commands/pages/astra-pcu-associate.adoc new file mode 100644 index 0000000..c053ec7 --- /dev/null +++ b/modules/commands/pages/astra-pcu-associate.adoc @@ -0,0 +1,57 @@ += astra pcu associate + +[source,shell] +---- +astra pcu associate [-qV] [--if-not-exists] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + GROUP TARGET + +---- + + +Associate a PCU group to a datacenter + + + + + +== Options + +`GROUP`:: The name or ID of the PCU group to operate on +`TARGET`:: PCU association target (database name/id or datacenter id) +`--if-not-exists`:: Don't error if the association already exists + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Associate a specific datacenter to a PCU group +$ astra pcu associate my_pcu ee6991af-7783-4de9-8da0-c7fa250c89e2-1 + +# Associate a database with a single datacenter to a PCU group +$ astra pcu associate my_pcu my_database +---- + + diff --git a/modules/commands/pages/astra-pcu-create.adoc b/modules/commands/pages/astra-pcu-create.adoc new file mode 100644 index 0000000..8405938 --- /dev/null +++ b/modules/commands/pages/astra-pcu-create.adoc @@ -0,0 +1,66 @@ += astra pcu create + +[source,shell] +---- +astra pcu create [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [-c=CLOUD] [--color=WHEN] [-d=DESC] [-it=TYPE] [--max=MAX] + [--min=MIN] [-o=FORMAT] [-pt=TYPE] [-r=REGION] + [--reserved=RESERVED] [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN + [--env=ENV]]] [--if-not-exists | --allow-duplicate-names] GROUP + +---- + + +Create a new PCU group + + + + + +== Options + +`GROUP`:: The name or ID of the PCU group to operate on +`--if-not-exists`:: Don't error if the pcu already exists +`--allow-duplicate-names`:: Allow multiple pcus with the same name +`-c`, `--cloud`:: Cloud provider this PCU will work in +`-r`, `--region`:: Cloud region this PCU will work in. **Use one of the `astra db list-regions-*` commands to see available regions.** +`-d`, `--description`:: Optional description for the PCU group +`-it`, `--instance-type`:: Cache type for the PCU group +`-pt`, `--provision-type`:: Provision type for the PCU group +`--min`:: Minimum capacity units for the PCU group +`--max`:: Maximum capacity units for the PCU group +`--reserved`:: Reserved capacity units for the PCU group + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Create a basic pcu group +$ astra pcu create my_pcu -c AWS -r us-west-2 + +# Create a pcu group if it doesn't already exist +$ astra pcu create my_pcu --region us-east1 --if-not-exists +---- + + diff --git a/modules/commands/pages/astra-pcu-delete.adoc b/modules/commands/pages/astra-pcu-delete.adoc new file mode 100644 index 0000000..26d2674 --- /dev/null +++ b/modules/commands/pages/astra-pcu-delete.adoc @@ -0,0 +1,59 @@ += astra pcu delete + +[source,shell] +---- +astra pcu delete [-qV] [--if-exists] [--no-input] [--[no-]spinner] [--yes] + [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] [GROUP] + +---- + + +Delete an existing Pcu group + + + + + +== Options + +`GROUP`:: The name or ID of the PCU group to work with +`--if-exists`:: Do not fail if PCU group does not exist +`--yes`:: Force deletion of PCU group without prompting + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Delete an existing Pcu group +$ astra pcu delete my_pcu + +# Delete an existing Pcu group without confirmation (required for non-interactive shells) +$ astra pcu delete my_pcu --yes + +# Delete an existing Pcu group without failing if it does not exist +$ astra pcu delete my_pcu --if-exists +---- + + diff --git a/modules/commands/pages/astra-pcu-disassociate.adoc b/modules/commands/pages/astra-pcu-disassociate.adoc new file mode 100644 index 0000000..ffe963d --- /dev/null +++ b/modules/commands/pages/astra-pcu-disassociate.adoc @@ -0,0 +1,57 @@ += astra pcu disassociate + +[source,shell] +---- +astra pcu disassociate [-qV] [--if-exists] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + GROUP TARGET + +---- + + +Disassociate a PCU group to a datacenter + + + + + +== Options + +`GROUP`:: The name or ID of the PCU group to operate on +`TARGET`:: PCU association target (database name/id or datacenter id) +`--if-exists`:: Don't error if the association doesn't exist + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Disassociate a specific datacenter from a PCU group +$ astra pcu disassociate my_pcu ee6991af-7783-4de9-8da0-c7fa250c89e2-1 + +# Disassociate a database with a single datacenter from a PCU group +$ astra pcu disassociate my_pcu my_database +---- + + diff --git a/modules/commands/pages/astra-pcu-get.adoc b/modules/commands/pages/astra-pcu-get.adoc new file mode 100644 index 0000000..d8ae857 --- /dev/null +++ b/modules/commands/pages/astra-pcu-get.adoc @@ -0,0 +1,58 @@ += astra pcu get + +[source,shell] +---- +astra pcu get [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-k=KEY] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [GROUP] + +---- + + +Get information about a specific PCU group. + +== Aliases + +`astra pcu describe` + + + + +== Options + +`GROUP`:: The name or ID of the PCU group to work with +`-k`, `--key`:: Specific PCU group attribute to retrieve + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Get information about a specific PCU group +$ astra pcu get my_pcu + +# Get a specific attribute of a PCU group +$ astra pcu get my_pcu --key id +---- + + diff --git a/modules/commands/pages/astra-pcu-list-associations.adoc b/modules/commands/pages/astra-pcu-list-associations.adoc new file mode 100644 index 0000000..ba40d76 --- /dev/null +++ b/modules/commands/pages/astra-pcu-list-associations.adoc @@ -0,0 +1,52 @@ += astra pcu list-associations + +[source,shell] +---- +astra pcu list-associations [-aqV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] [GROUP] + +---- + + +List the associations of a PCU group + + + + + +== Options + +`GROUP`:: The name or ID of the PCU group to work with +`-a`, `--all`:: List all associations for all of your PCU groups + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# List the associations of a PCU group +$ astra pcu list-associations my_pu +---- + + diff --git a/modules/commands/pages/astra-pcu-list.adoc b/modules/commands/pages/astra-pcu-list.adoc new file mode 100644 index 0000000..1700845 --- /dev/null +++ b/modules/commands/pages/astra-pcu-list.adoc @@ -0,0 +1,53 @@ += astra pcu list + +[source,shell] +---- +astra pcu list [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] + +---- + + +List your PCU groups + +== Aliases + +`astra pcu` + + + + +== Options + + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# List all your PCU groups +$ astra pcu list +---- + + diff --git a/modules/commands/pages/astra-pcu-park.adoc b/modules/commands/pages/astra-pcu-park.adoc new file mode 100644 index 0000000..27cf2d4 --- /dev/null +++ b/modules/commands/pages/astra-pcu-park.adoc @@ -0,0 +1,53 @@ += astra pcu park + +[source,shell] +---- +astra pcu park [-qV] [--[no-]async] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [--timeout=] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] [GROUP] + +---- + + +Park an existing PCU group + + + + + +== Options + +`GROUP`:: The name or ID of the PCU group to work with +`--async`:: Do not wait for the database to become active +`--timeout`:: How long the command should wait for the database to become active + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Park an existing PCU group +$ astra pcu park my_pcu +---- + + diff --git a/modules/commands/pages/astra-pcu-status.adoc b/modules/commands/pages/astra-pcu-status.adoc new file mode 100644 index 0000000..0086049 --- /dev/null +++ b/modules/commands/pages/astra-pcu-status.adoc @@ -0,0 +1,51 @@ += astra pcu status + +[source,shell] +---- +astra pcu status [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [GROUP] + +---- + + +Get the current status of a PCU group. + + + + + +== Options + +`GROUP`:: The name or ID of the PCU group to work with + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Get the status of a PCU group +$ astra db status my_db +---- + + diff --git a/modules/commands/pages/astra-pcu-transfer-association.adoc b/modules/commands/pages/astra-pcu-transfer-association.adoc new file mode 100644 index 0000000..1a508fb --- /dev/null +++ b/modules/commands/pages/astra-pcu-transfer-association.adoc @@ -0,0 +1,57 @@ += astra pcu transfer-association + +[source,shell] +---- +astra pcu transfer-association [-qV] [--if-not-exists] [--no-input] [--[no-] + spinner] [--dump-logs[=FILE]] [--color=WHEN] + [-o=FORMAT] -t=GROUP [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [-f=GROUP | + --or-create] TARGET + +---- + + +Transfer an association from one PCU group to another + + + + + +== Options + +`TARGET`:: PCU association target (database name/id or datacenter id) +`-t`, `--to`:: The PCU group to transfer the association to +`--if-not-exists`:: Don't error if the association already exists +`-f`, `--from`:: The PCU group which initially holds the association. May be omitted to let the CLI automatically detect it +`--or-create`:: If the datacenter is not already associated to a PCU group, create the association first + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Transfer a datacenter association association from one PCU group to another +$ astra pcu transfer-association ee6991af-7783-4de9-8da0-c7fa250c89e2-1 --from pcu_1 --to pcu_2 +---- + + diff --git a/modules/commands/pages/astra-pcu-unpark.adoc b/modules/commands/pages/astra-pcu-unpark.adoc new file mode 100644 index 0000000..7c41697 --- /dev/null +++ b/modules/commands/pages/astra-pcu-unpark.adoc @@ -0,0 +1,53 @@ += astra pcu unpark + +[source,shell] +---- +astra pcu unpark [-qV] [--[no-]async] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [--timeout=] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] [GROUP] + +---- + + +Unpark a parked PCU group + + + + + +== Options + +`GROUP`:: The name or ID of the PCU group to work with +`--async`:: Do not wait for the database to become active +`--timeout`:: How long the command should wait for the database to become active + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Unpark a parked PCU group +$ astra pcu unpark my_pcu +---- + + diff --git a/modules/commands/pages/astra-pcu-update.adoc b/modules/commands/pages/astra-pcu-update.adoc new file mode 100644 index 0000000..832062e --- /dev/null +++ b/modules/commands/pages/astra-pcu-update.adoc @@ -0,0 +1,63 @@ += astra pcu update + +[source,shell] +---- +astra pcu update [-qV] [--allow-duplicate-names] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [-c=CLOUD] [--color=WHEN] [-d=DESC] + [-it=TYPE] [--max=MAX] [--min=MIN] [-o=FORMAT] [-pt=TYPE] + [-r=REGION] [--reserved=RESERVED] [-t=TITLE] [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] [GROUP] + +---- + + +Update an existing PCU group + + + + + +== Options + +`GROUP`:: The name or ID of the PCU group to work with +`--allow-duplicate-names`:: Allow multiple pcus with the same name +`-t`, `--title`:: New title for the PCU group +`-c`, `--cloud`:: Cloud provider this PCU will work in +`-r`, `--region`:: Cloud region this PCU will work in. **Use one of the `astra db list-regions-*` commands to see available regions.** +`-d`, `--description`:: Optional description for the PCU group +`-it`, `--instance-type`:: Cache type for the PCU group +`-pt`, `--provision-type`:: Provision type for the PCU group +`--min`:: Minimum capacity units for the PCU group +`--max`:: Maximum capacity units for the PCU group +`--reserved`:: Reserved capacity units for the PCU group + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Update an existing PCU group +$ astra pcu update my_pcu --tile new_title --min 2 --max 5 +---- + + diff --git a/modules/commands/pages/astra-pcu.adoc b/modules/commands/pages/astra-pcu.adoc new file mode 100644 index 0000000..edcd9ca --- /dev/null +++ b/modules/commands/pages/astra-pcu.adoc @@ -0,0 +1,66 @@ += astra pcu + +[source,shell] +---- +astra pcu [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN + [--env=ENV]]] [COMMAND] + +---- + + +Manage your PCU groups and associations + + +**Alias of `astra pcu list`** + + +== Subcommands + +* xref:astra-pcu-list.adoc[astra pcu list] +* xref:astra-pcu-get.adoc[astra pcu get] +* xref:astra-pcu-status.adoc[astra pcu status] +* xref:astra-pcu-park.adoc[astra pcu park] +* xref:astra-pcu-unpark.adoc[astra pcu unpark] +* xref:astra-pcu-create.adoc[astra pcu create] +* xref:astra-pcu-update.adoc[astra pcu update] +* xref:astra-pcu-delete.adoc[astra pcu delete] +* xref:astra-pcu-associate.adoc[astra pcu associate] +* xref:astra-pcu-disassociate.adoc[astra pcu disassociate] +* xref:astra-pcu-list-associations.adoc[astra pcu list-associations] +* xref:astra-pcu-transfer-association.adoc[astra pcu transfer-association] + + +== Options + + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# List all your PCU groups +$ astra pcu +---- + + diff --git a/modules/commands/pages/astra-role-get.adoc b/modules/commands/pages/astra-role-get.adoc new file mode 100644 index 0000000..28ddbca --- /dev/null +++ b/modules/commands/pages/astra-role-get.adoc @@ -0,0 +1,57 @@ += astra role get + +[source,shell] +---- +astra role get [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] ROLE + +---- + + +Show details for a specific role + +== Aliases + +`astra role describe` + + + + +== Options + +`ROLE`:: Role name/id to get + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Get details for a specific role by name +$ astra role get "Database Administrator" + +# Get details for a specific role by ID +$ astra role get "12345678-abcd-1234-abcd-123456789012" +---- + + diff --git a/modules/commands/pages/astra-role-list.adoc b/modules/commands/pages/astra-role-list.adoc new file mode 100644 index 0000000..f7253f4 --- /dev/null +++ b/modules/commands/pages/astra-role-list.adoc @@ -0,0 +1,50 @@ += astra role list + +[source,shell] +---- +astra role list [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] + +---- + + +Display all roles + + + + + +== Options + + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# List all available roles in your organization +$ astra role list +---- + + diff --git a/modules/commands/pages/astra-role.adoc b/modules/commands/pages/astra-role.adoc new file mode 100644 index 0000000..d078a4d --- /dev/null +++ b/modules/commands/pages/astra-role.adoc @@ -0,0 +1,34 @@ += astra role + +[source,shell] +---- +astra role [COMMAND] + +---- + + +Discover Astra roles + + + +== Subcommands + +* xref:astra-role-list.adoc[astra role list] +* xref:astra-role-get.adoc[astra role get] + + +== Options + + + +== Examples +[source,bash] +---- +# List all available roles +$ astra role list + +# Get details for a specific role +$ astra role get "Database Administrator" +---- + + diff --git a/modules/commands/pages/astra-setup.adoc b/modules/commands/pages/astra-setup.adoc new file mode 100644 index 0000000..21a87b5 --- /dev/null +++ b/modules/commands/pages/astra-setup.adoc @@ -0,0 +1,45 @@ += astra setup + +[source,shell] +---- +astra setup [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-e=ENV] [--name=NAME] [-o=FORMAT] [-t=TOKEN] + +---- + + +Interactively set up the Astra CLI and create profiles + +See ``astra config create`` for a programmatic way to create profiles without interaction. + + + + + +== Options + +`-t`, `--token`:: Token to use authenticate each call. If not provided, you will be prompted for it +`-e`, `--env`:: Astra environment for the token to target. If not provided, you will be prompted for it +`--name`:: Optional name for the profile. If not provided, you will be prompted for it + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + + +== Examples +[source,bash] +---- +# Start the interactive setup process +$ astra setup +---- + + diff --git a/modules/commands/pages/astra-shellenv.adoc b/modules/commands/pages/astra-shellenv.adoc new file mode 100644 index 0000000..20b5232 --- /dev/null +++ b/modules/commands/pages/astra-shellenv.adoc @@ -0,0 +1,54 @@ += astra shellenv + +[source,shell] +---- +astra shellenv [--ignore-multiple-paths] [--no-update-notifier] + [--home=<$home>] [--rc=<$rc>] + +---- + + +Completions, configuration, and more + +Eval-ing the output of this command will: + + * Add the binary to your PATH + + * Enable shell completions + + * Optionally set any other configuration environment variables. + +Intended to be added to your shell profile (``.zprofile``, ``.bash_profile``, ``.profile``, etc.), but you can technically just eval it in any shell session to get completions and update your PATH for that session. + + + + + +== Options + +`--home`:: Sets the ``ASTRA_HOME`` env var. See ``astra config home path -h`` for how this is resolved. +`--rc`:: Sets the ``ASTRARC`` env var. See ``astra config path -h`` for how this is resolved. +`--ignore-multiple-paths`:: Ignore warnings about multiple astra home folders or astrarc files being present. Sets ``ASTRA_IGNORE_MULTIPLE_PATHS=true`` under the hood. +`--no-update-notifier`:: Disables background update checks notifications. Sets ``ASTRA_NO_UPDATE_NOTIFIER=true`` under the hood. + + +== Examples +[source,bash] +---- +# Put this in your shell profile (e.g. ``~/.zprofile``) to generate completions and set your PATH +$ eval "$(/path/to/astra shellenv)" + +# Set a custom ``ASTRA_HOME`` path +$ eval "$(/path/to/astra shellenv --home /path/to/astra/home)" + +# Set a custom ``ASTRARC`` path +$ eval "$(/path/to/astra shellenv --rc /path/to/astrarc)" + +# Disable update notifications +$ eval "$(/path/to/astra shellenv --no-update-notifier)" + +# Ignore warnings about multiple astra home folders or astrarc files +$ eval "$(/path/to/astra shellenv --ignore-multiple-paths)" +---- + + diff --git a/modules/commands/pages/astra-streaming-create.adoc b/modules/commands/pages/astra-streaming-create.adoc new file mode 100644 index 0000000..d4b0fff --- /dev/null +++ b/modules/commands/pages/astra-streaming-create.adoc @@ -0,0 +1,68 @@ += astra streaming create + +[source,shell] +---- +astra streaming create [-qV] [--if-not-exists] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + ([--plan=PLAN] | -e=EMAIL | (--cluster=CLUSTER | + [-r=REGION [-c=CLOUD]])) TENANT + +---- + + +Create a new streaming tenant + + + + + +== Options + +`TENANT`:: The name of the tenant to operate on +`--if-not-exists`:: Don't error if the tenant already exists +`--plan`:: Plan for the tenant +`-e`, `--email`:: User email +`--cluster`:: Dedicated cluster, replacement for cloud/region +`-r`, `--region`:: Cloud provider region to provision +`-c`, `--cloud`:: The cloud provider where the tenant should be created. Inferred from the region if not provided. + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Create a basic streaming tenant in the 'us-east1' region +$ astra streaming create my_tenant --region us-east1 + +# Create a tenant with a specific cloud provider +$ astra streaming create my_tenant --region us-east1 --cloud AWS + +# Create a tenant with a dedicated cluster +$ astra streaming create my_tenant --cluster my_cluster + +# Create a tenant if it doesn't already exist +$ astra streaming create my_tenant --region us-east1 --if-not-exists +---- + + diff --git a/modules/commands/pages/astra-streaming-delete.adoc b/modules/commands/pages/astra-streaming-delete.adoc new file mode 100644 index 0000000..3b3186c --- /dev/null +++ b/modules/commands/pages/astra-streaming-delete.adoc @@ -0,0 +1,56 @@ += astra streaming delete + +[source,shell] +---- +astra streaming delete [-qV] [--if-exists] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + [TENANT] + +---- + + +Delete an existing streaming tenant + + + + + +== Options + +`TENANT`:: The name of the tenant to operate on +`--if-exists`:: Do not fail if tenant does not exist + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Delete an existing streaming tenant +$ astra streaming delete my_tenant + +# Delete an existing streaming tenant without failing if it does not exist +$ astra streaming delete my_tenant --if-exists +---- + + diff --git a/modules/commands/pages/astra-streaming-exist.adoc b/modules/commands/pages/astra-streaming-exist.adoc new file mode 100644 index 0000000..6c47aa0 --- /dev/null +++ b/modules/commands/pages/astra-streaming-exist.adoc @@ -0,0 +1,51 @@ += astra streaming exist + +[source,shell] +---- +astra streaming exist [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] TENANT + +---- + + +Show existence of a streaming tenant + + + + + +== Options + +`TENANT`:: The name of the tenant to operate on + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Check if a streaming tenant exists +$ astra streaming exist my_tenant +---- + + diff --git a/modules/commands/pages/astra-streaming-get.adoc b/modules/commands/pages/astra-streaming-get.adoc new file mode 100644 index 0000000..d40ca21 --- /dev/null +++ b/modules/commands/pages/astra-streaming-get.adoc @@ -0,0 +1,58 @@ += astra streaming get + +[source,shell] +---- +astra streaming get [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-k=KEY] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] + | [--token=TOKEN [--env=ENV]]] [TENANT] + +---- + + +Get the info about a streaming tenant. + +== Aliases + +`astra streaming describe` + + + + +== Options + +`TENANT`:: The name of the tenant to operate on +`-k`, `--key`:: Specific tenant attribute to retrieve + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Get information about a specific tenant +$ astra streaming get my_tenant + +# Get a specific attribute of a tenant +$ astra streaming get my_tenant --key region +---- + + diff --git a/modules/commands/pages/astra-streaming-list-clouds.adoc b/modules/commands/pages/astra-streaming-list-clouds.adoc new file mode 100644 index 0000000..2cb66b4 --- /dev/null +++ b/modules/commands/pages/astra-streaming-list-clouds.adoc @@ -0,0 +1,50 @@ += astra streaming list-clouds + +[source,shell] +---- +astra streaming list-clouds [-qV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + +---- + + +List all available cloud providers for Astra streaming tenants + + + + + +== Options + + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# List all available cloud providers for streaming tenants +$ astra streaming list-clouds +---- + + diff --git a/modules/commands/pages/astra-streaming-list-regions.adoc b/modules/commands/pages/astra-streaming-list-regions.adoc new file mode 100644 index 0000000..cacf925 --- /dev/null +++ b/modules/commands/pages/astra-streaming-list-regions.adoc @@ -0,0 +1,60 @@ += astra streaming list-regions + +[source,shell] +---- +astra streaming list-regions [-qV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [-c=FILTER[, + FILTER...]]... [-f=FILTER[,FILTER...]]... + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN + [--env=ENV]]] + +---- + + +List all available regions for Astra streaming tenants + + + + + +== Options + +`-f`, `--filter`:: Comma-separated case-insensitive partial-match filters on the region name +`-c`, `--cloud`:: Comma-separated list of cloud providers to filter on + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# List all available regions for streaming tenants +$ astra streaming list-regions + +# Filter by cloud provider +$ astra streaming list-regions --cloud aws,gcp + +# Filter by partial region name +$ astra streaming list-regions --filter us- +---- + + diff --git a/modules/commands/pages/astra-streaming-list.adoc b/modules/commands/pages/astra-streaming-list.adoc new file mode 100644 index 0000000..5424023 --- /dev/null +++ b/modules/commands/pages/astra-streaming-list.adoc @@ -0,0 +1,52 @@ += astra streaming list + +[source,shell] +---- +astra streaming list [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] + +---- + + +List your Astra streaming tenants + +== Aliases + +`astra streaming` + + + + +== Options + + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- + +---- + + diff --git a/modules/commands/pages/astra-streaming-pulsar-path.adoc b/modules/commands/pages/astra-streaming-pulsar-path.adoc new file mode 100644 index 0000000..2b3d89d --- /dev/null +++ b/modules/commands/pages/astra-streaming-pulsar-path.adoc @@ -0,0 +1,58 @@ += astra streaming pulsar path + +[source,shell] +---- +astra streaming pulsar path [-qV] [--if-exists] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN + [--env=ENV]]] + +---- + + +Get the path to the currently installed pulsar executable + + + + + +== Options + +`--if-exists`:: Only return path if pulsar exists, don't install automatically + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Get the path to the pulsar executable +$ astra streaming pulsar path + +# Use the pulsar exe to run a custom command +$ $(astra streaming pulsar path) --help + +# Get path only if pulsar exists, don't install +$ astra streaming pulsar path --if-exists +---- + + diff --git a/modules/commands/pages/astra-streaming-pulsar-shell.adoc b/modules/commands/pages/astra-streaming-pulsar-shell.adoc new file mode 100644 index 0000000..055d5fd --- /dev/null +++ b/modules/commands/pages/astra-streaming-pulsar-shell.adoc @@ -0,0 +1,56 @@ += astra streaming pulsar shell + +[source,shell] +---- +astra streaming pulsar shell [-FqV] [--no-input] [-np] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN + [--env=ENV]]] [-e=STATEMENT | -f=FILE] [TENANT] + +---- + + +Launch Apache Pulsar shell for a streaming tenant + + + + + +== Options + +`TENANT`:: The name of the tenant to connect to +`-F`, `--fail-on-error`:: Interrupt the shell if a command throws an exception +`-np`, `--no-progress`:: Display raw output of the commands without progress visualization +`-e`, `--execute`:: Execute the statement and quit +`-f`, `--file`:: Input filename with a list of commands to be executed. Each command must be separated by a newline + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Launch pulsar shell for a tenant +$ astra streaming pulsar shell my_tenant +---- + + diff --git a/modules/commands/pages/astra-streaming-pulsar-token.adoc b/modules/commands/pages/astra-streaming-pulsar-token.adoc new file mode 100644 index 0000000..5da741b --- /dev/null +++ b/modules/commands/pages/astra-streaming-pulsar-token.adoc @@ -0,0 +1,51 @@ += astra streaming pulsar-token + +[source,shell] +---- +astra streaming pulsar-token [-qV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] TENANT + +---- + + +Get the Pulsar token for a streaming tenant + + + + + +== Options + +`TENANT`:: The name of the tenant to operate on + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Get the Pulsar token for a tenant +$ astra streaming pulsar-token my_tenant +---- + + diff --git a/modules/commands/pages/astra-streaming-pulsar-version.adoc b/modules/commands/pages/astra-streaming-pulsar-version.adoc new file mode 100644 index 0000000..63050e6 --- /dev/null +++ b/modules/commands/pages/astra-streaming-pulsar-version.adoc @@ -0,0 +1,50 @@ += astra streaming pulsar version + +[source,shell] +---- +astra streaming pulsar version [-qV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + +---- + + +Display the currently installed pulsar's version + + + + + +== Options + + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Display pulsar's version information +$ astra streaming pulsar version +---- + + diff --git a/modules/commands/pages/astra-streaming-pulsar.adoc b/modules/commands/pages/astra-streaming-pulsar.adoc new file mode 100644 index 0000000..3b5db45 --- /dev/null +++ b/modules/commands/pages/astra-streaming-pulsar.adoc @@ -0,0 +1,38 @@ += astra streaming pulsar + +[source,shell] +---- +astra streaming pulsar [COMMAND] + +---- + + +Apache Pulsar operations for your Astra streaming tenants + + + +== Subcommands + +* xref:astra-streaming-pulsar-shell.adoc[astra streaming pulsar shell] +* xref:astra-streaming-pulsar-version.adoc[astra streaming pulsar version] +* xref:astra-streaming-pulsar-path.adoc[astra streaming pulsar path] + + +== Options + + + +== Examples +[source,bash] +---- +# Launch pulsar shell for a tenant +$ astra streaming pulsar shell my_tenant + +# Get pulsar version +$ astra streaming pulsar version + +# Get pulsar executable path +$ astra streaming pulsar path +---- + + diff --git a/modules/commands/pages/astra-streaming-status.adoc b/modules/commands/pages/astra-streaming-status.adoc new file mode 100644 index 0000000..4d60cec --- /dev/null +++ b/modules/commands/pages/astra-streaming-status.adoc @@ -0,0 +1,51 @@ += astra streaming status + +[source,shell] +---- +astra streaming status [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [TENANT] + +---- + + +Get the current status of a streaming tenant. + + + + + +== Options + +`TENANT`:: The name of the tenant to operate on + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Get the status of a streaming tenant +$ astra streaming status my_tenant +---- + + diff --git a/modules/commands/pages/astra-streaming.adoc b/modules/commands/pages/astra-streaming.adoc new file mode 100644 index 0000000..dc38dd8 --- /dev/null +++ b/modules/commands/pages/astra-streaming.adoc @@ -0,0 +1,63 @@ += astra streaming + +[source,shell] +---- +astra streaming [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [COMMAND] + +---- + + +Manage Astra streaming tenants + + +**Alias of `astra streaming list`** + + +== Subcommands + +* xref:astra-streaming-list.adoc[astra streaming list] +* xref:astra-streaming-get.adoc[astra streaming get] +* xref:astra-streaming-create.adoc[astra streaming create] +* xref:astra-streaming-delete.adoc[astra streaming delete] +* xref:astra-streaming-exist.adoc[astra streaming exist] +* xref:astra-streaming-status.adoc[astra streaming status] +* xref:astra-streaming-pulsar.adoc[astra streaming pulsar] +* xref:astra-streaming-pulsar-token.adoc[astra streaming pulsar-token] +* xref:astra-streaming-list-regions.adoc[astra streaming list-regions] +* xref:astra-streaming-list-clouds.adoc[astra streaming list-clouds] + + +== Options + + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- + +---- + + diff --git a/modules/commands/pages/astra-token-create.adoc b/modules/commands/pages/astra-token-create.adoc new file mode 100644 index 0000000..bc6bec3 --- /dev/null +++ b/modules/commands/pages/astra-token-create.adoc @@ -0,0 +1,52 @@ += astra token create + +[source,shell] +---- +astra token create [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-d=DESC] [-o=FORMAT] -r=ROLE [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + +---- + + +Create a new token + + + + + +== Options + +`-r`, `--role`:: The role for this token +`-d`, `--description`:: An optional description for this token + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Create a token with a specific role +$ astra token create --role "Organization Administrator" +---- + + diff --git a/modules/commands/pages/astra-token-delete.adoc b/modules/commands/pages/astra-token-delete.adoc new file mode 100644 index 0000000..e324b03 --- /dev/null +++ b/modules/commands/pages/astra-token-delete.adoc @@ -0,0 +1,58 @@ += astra token delete + +[source,shell] +---- +astra token delete [-qV] [--if-exists] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] TOKEN + +---- + + +Delete a token + +== Aliases + +`astra token revoke` + + + + +== Options + +`TOKEN`:: Token identifier +`--if-exists`:: Do not fail if token does not exist + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Delete a specific token +$ astra token delete + +# Delete a token without failing if it doesn't exist +$ astra token delete --if-exists +---- + + diff --git a/modules/commands/pages/astra-token-get.adoc b/modules/commands/pages/astra-token-get.adoc new file mode 100644 index 0000000..7fba8f3 --- /dev/null +++ b/modules/commands/pages/astra-token-get.adoc @@ -0,0 +1,55 @@ += astra token get + +[source,shell] +---- +astra token get [-cqV] [--no-input] [--[no-]spinner] [--validate] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] + +---- + + +Show your current token + +== Aliases + +`astra token` + + + + +== Options + +`-c`, `--copy`:: Copy the token to clipboard instead of printing it +`--validate`:: Validates the token before returning it + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Show your current token +$ astra token get +---- + + diff --git a/modules/commands/pages/astra-token-list.adoc b/modules/commands/pages/astra-token-list.adoc new file mode 100644 index 0000000..0290f81 --- /dev/null +++ b/modules/commands/pages/astra-token-list.adoc @@ -0,0 +1,50 @@ += astra token list + +[source,shell] +---- +astra token list [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] + +---- + + +List your tokens' information + + + + + +== Options + + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# List your tokens' information +$ astra token list +---- + + diff --git a/modules/commands/pages/astra-token.adoc b/modules/commands/pages/astra-token.adoc new file mode 100644 index 0000000..1fb379f --- /dev/null +++ b/modules/commands/pages/astra-token.adoc @@ -0,0 +1,60 @@ += astra token + +[source,shell] +---- +astra token [-cqV] [--no-input] [--[no-]spinner] [--validate] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [COMMAND] + +---- + + +Manage your Astra tokens + + +**Alias of `astra token get`** + + +== Subcommands + +* xref:astra-token-list.adoc[astra token list] +* xref:astra-token-get.adoc[astra token get] +* xref:astra-token-create.adoc[astra token create] +* xref:astra-token-delete.adoc[astra token delete] + + +== Options + +`-c`, `--copy`:: Copy the token to clipboard instead of printing it +`--validate`:: Validates the token before returning it + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Show your current token +$ astra token +---- + + diff --git a/modules/commands/pages/astra-upgrade.adoc b/modules/commands/pages/astra-upgrade.adoc new file mode 100644 index 0000000..a7019f2 --- /dev/null +++ b/modules/commands/pages/astra-upgrade.adoc @@ -0,0 +1,56 @@ += astra upgrade + +[source,shell] +---- +astra upgrade [-qV] [--allow-reinstall] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] [-v=TAG | --pre] + +---- + + +Upgrade your Astra CLI installation + +Update notifications may occur periodically when a new version is available. + +To opt out of Update notifications, set ``ASTRA_NO_UPDATE_NOTIFIER=true``, or, even better, use the ``--no-update-notifier`` flag on the ``astra shellenv`` invocation in your shell profile (if it's set up). + + + + + +== Options + +`--allow-reinstall`:: Allow re-installing the same version +`-v`, `--version`:: Version to upgrade to (default: latest) +`--pre`, `--prerelease`:: Include pre-releases when looking for the latest version + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + + +== Examples +[source,bash] +---- +# Upgrade to the latest stable version +$ astra upgrade + +# Upgrade to the latest version, including pre-releases +$ astra upgrade --pre + +# Upgrade (or downgrade!) to a specific version +$ astra upgrade --version 1.1.0 + +# Opt out of upgrade notifications permanently in your shell profile +$ eval "$(/path/to/astra shellenv --no-update-notifier)" +---- + + diff --git a/modules/commands/pages/astra-user-delete.adoc b/modules/commands/pages/astra-user-delete.adoc new file mode 100644 index 0000000..77c063f --- /dev/null +++ b/modules/commands/pages/astra-user-delete.adoc @@ -0,0 +1,55 @@ += astra user delete + +[source,shell] +---- +astra user delete [-qV] [--if-exists] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] USER + +---- + + +Delete an existing user + + + + + +== Options + +`USER`:: User email/id to delete +`--if-exists`:: Do not fail if user does not exist + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Delete a specific user +$ astra user delete john@example.com + +# Delete a user without failing if they doesn't exist +$ astra user delete john@example.com --if-exists +---- + + diff --git a/modules/commands/pages/astra-user-get.adoc b/modules/commands/pages/astra-user-get.adoc new file mode 100644 index 0000000..da752f7 --- /dev/null +++ b/modules/commands/pages/astra-user-get.adoc @@ -0,0 +1,57 @@ += astra user get + +[source,shell] +---- +astra user get [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] USER + +---- + + +Show details for a specific user + +== Aliases + +`astra user describe` + + + + +== Options + +`USER`:: User email/id to get + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Get details for a specific user by email +$ astra user get john@example.com + +# Get details for a specific user by ID +$ astra user get 12345678-abcd-1234-abcd-123456789012 +---- + + diff --git a/modules/commands/pages/astra-user-invite.adoc b/modules/commands/pages/astra-user-invite.adoc new file mode 100644 index 0000000..ff64f6f --- /dev/null +++ b/modules/commands/pages/astra-user-invite.adoc @@ -0,0 +1,60 @@ += astra user invite + +[source,shell] +---- +astra user invite [-qV] [--if-not-exists] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] [-r=<$roles>[, + <$roles>...]]... [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN + [--env=ENV]]] USER + +---- + + +Invite a user to an organization + + + + + +== Options + +`USER`:: User email/id to invite +`-r`, `--roles`:: List of roles to assign the user +`--if-not-exists`:: Do not fail if user already exists + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# Invite a user with default "Database Administrator" role +$ astra user invite john@example.com + +# Invite a user with specific roles +$ astra user invite john@example.com --role 'R/W User' --role 'Billing Admin' + +# Invite a user without failing if they already exist +$ astra user invite john@example.com --if-not-exists +---- + + diff --git a/modules/commands/pages/astra-user-list.adoc b/modules/commands/pages/astra-user-list.adoc new file mode 100644 index 0000000..d3515ef --- /dev/null +++ b/modules/commands/pages/astra-user-list.adoc @@ -0,0 +1,50 @@ += astra user list + +[source,shell] +---- +astra user list [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] + +---- + + +List all users in the org + + + + + +== Options + + +.Common Options +[%collapsible] +==== +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +==== + +.Connection Options +[%collapsible] +==== +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +==== + + +== Examples +[source,bash] +---- +# List all users in your organization +$ astra user list +---- + + diff --git a/modules/commands/pages/astra-user.adoc b/modules/commands/pages/astra-user.adoc new file mode 100644 index 0000000..3afcd92 --- /dev/null +++ b/modules/commands/pages/astra-user.adoc @@ -0,0 +1,33 @@ += astra user + +[source,shell] +---- +astra user [COMMAND] + +---- + + +Manage users in your organization + + + +== Subcommands + +* xref:astra-user-list.adoc[astra user list] +* xref:astra-user-get.adoc[astra user get] +* xref:astra-user-invite.adoc[astra user invite] +* xref:astra-user-delete.adoc[astra user delete] + + +== Options + + + +== Examples +[source,bash] +---- +# List all your Astra users +$ astra user list +---- + + diff --git a/modules/quickstarts/pages/cqlsh.adoc b/modules/quickstarts/pages/cqlsh.adoc new file mode 100644 index 0000000..b01955d --- /dev/null +++ b/modules/quickstarts/pages/cqlsh.adoc @@ -0,0 +1,180 @@ += Issue CQL commands with cqlsh in the {product} +:navtitle: CQL quickstart + +The {cass-short} Query Language Shell (`cqlsh`) is a utility that you can use to issue xref:astra@cql:reference:cql-quick-reference.adoc[CQL commands] to your {astra-db} database. + +The {product} provides embedded `cqlsh` support by downloading and installing the `cqlsh` utility in the background and exposing it through the `xref:commands:astra-db-cqlsh.adoc[]` commands. +This can act as a convenient alternative to installing and configuring a xref:astra-db-serverless:cql:develop-with-cql.adoc#connect-to-the-cql-shell[standalone cqlsh]. + +The `cqlsh` utility isn't installed by default with the {product}. +The first time you run an `astra db cqlsh` command, the {product} downloads and installs the `cqlsh` utility into the {product} home directory (`xref:ROOT:manage-cli.adoc#file-locations[~/.astra]`). + +All `astra db cqlsh` commands require a database name or ID. +The first time you connect to a specific database, {product} downloads the database's {scb} into the {product} home directory. + +== Prerequisites + +To use `cqlsh` commands, you must have a supported version of Python installed on your system. + +The underlying `cqlsh` utility requires Python 2.7 with TLS support, or any version of Python from 3.6 through 3.11. +Python versions 3.12 and later are not supported. +For more details, see this https://support.datastax.com/s/article/cqlsh-may-fail-with-A-Python-installation-with-SSL-is-required-to-connect-to-a-cloud-cluster-when-connecting-to-Astra[support article] + +Any supported version of Python must be available in your system's `PATH` for the {product} to use it. +It does not require that the supported version be your system's default version of Python. + +If the {product} reports `ModuleNotFoundError` after running any of the `astra db cqlsh` commands, you might not have a supported version of Python available in your system's `PATH`. + +== Start an interactive cqlsh session + +Use the `xref:commands:astra-db-cqlsh-start.adoc[]` command to start `cqlsh` in interactive mode: + +[source,shell,subs="+quotes"] +---- +astra db cqlsh start **DB_ID** +---- + +.Result +[%collapsible] +==== +[source,console] +---- +[INFO] Patched cqlsh script to try known supported Python versions first +Connected to cndb at 127.0.0.1:9042. +[cqlsh 6.8.0 | Cassandra 4.0.0.6816 | CQL spec 3.4.5 | Native protocol v4] +Use HELP for help. +token@cqlsh> +---- +==== + +To exit `cqlsh`, type `exit` or `quit;` and then press kbd:[Enter]. + +== Issue a CQL statement directly + +Use the `xref:commands:astra-db-cqlsh-exec.adoc[]` command to issue a CQL statement directly from your terminal without starting an interactive `cqlsh` session: + +[source,shell,subs="+quotes"] +---- +astra db cqlsh exec **DB_ID** "describe keyspaces;" +---- + +.Result +[%collapsible] +==== +[source,console] +---- +system_auth data_endpoint_auth default_keyspace system_views +my_keyspace system system_traces system_virtual_schema +system_schema datastax_sla my_keyspace2 +---- +==== + +CQL statements must be enclosed in double quotes (`""`). + +=== Execute a CQL file + +Use the `-f` / `--file` option with the `xref:commands:astra-db-cqlsh-exec.adoc[]` command to execute a CQL file: + +[source,shell,subs="+quotes"] +---- +astra db cqlsh exec **DB_ID** -f sample.cql +---- + +.Example CQL file +[%collapsible] +==== +.sample.cql +[source,cql] +---- +-- Use a specific keyspace +USE default_keyspace; + +-- Create a table +CREATE TABLE IF NOT EXISTS users ( + id UUID PRIMARY KEY, + name TEXT, + email TEXT +); + +-- Insert some data +INSERT INTO users (id, name, email) VALUES (uuid(), 'Alice', 'alice@example.com'); +INSERT INTO users (id, name, email) VALUES (uuid(), 'Bob', 'bob@example.com'); + +-- Query the data +SELECT * FROM users; +---- +==== + +.Result +[%collapsible] +==== +[source,console] +---- + id | email | name +--------------------------------------+-------------------+------- + 8b901d74-ac31-48e2-a403-dbcee8efe935 | bob@example.com | Bob + 0d712e1e-b764-4bbd-b587-579b75f29f32 | alice@example.com | Alice + +(2 rows) +---- +==== + +== Connect to a specific keyspace + +Use the `-k` / `--keyspace` option with the `xref:commands:astra-db-cqlsh-start.adoc[]` and `xref:commands:astra-db-cqlsh-exec.adoc[]` commands to connect directly to a specific keyspace: + +[source,shell,subs="+quotes"] +---- +astra db cqlsh start **DB_ID** -k **KEYSPACE_NAME** +---- + +.Result +[%collapsible] +==== +[source,console] +---- +Connected to cndb at 127.0.0.1:9042. +[cqlsh 6.8.0 | Cassandra 4.0.0.6816 | CQL spec 3.4.5 | Native protocol v4] +Use HELP for help. +token@cqlsh:my_keyspace> +---- +==== + +[source,shell,subs="+quotes"] +---- +astra db cqlsh exec **DB_ID** -k **KEYSPACE_NAME** "DESC TABLES" +---- + +.Result +[%collapsible] +==== +[source,console] +---- +repairs view_builds_in_progress paxos transferred_ranges +available_ranges peers size_estimates +batches compaction_history built_views +prepared_statements sstable_activity range_xfers +"IndexInfo" peer_events local +---- +==== + +//// +TODO: Consider adding the following sections later: + +1. Executing a statement from stdout +``` +# Normal usage +echo "" | astra db cqlsh DB + +# or use - to explicitly specify that you're reading from stdin +echo "" | astra db cqlsh DB - + +# Or just type in what you want to into the terminal using `\` to create a new line +astra db cqlsh DB +``` +2. Using the cqlsh binary directly +``` +$(astra db cqlsh path) --version +``` +3. A section that's just a list of links to the command references for the various `cqlsh` commands `astra` offers +////