docs: Restish cli guide - #450
Draft
GabriellePoncey wants to merge 2 commits into
Draft
Conversation
Adds a guide for using restish as a cli tool. Document a quickstart process (rapid installation and experimentation), profile management, project configuration and mtls profile setup, database config files and secrets. PLAT-671
📝 WalkthroughWalkthroughRestish CLI documentation is added. It covers installation, profiles, project configuration, TLS settings, database configuration files, and secret handling. The new guide is linked under the API navigation. ChangesRestish CLI documentation
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Up to standards ✅🟢 Issues
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/api/restish.md`:
- Around line 187-210: Update the example configuration in the REST API guide so
the canonical databases/example.json contains no real password or other secrets.
Demonstrate the initial create request using a separate create-only secrets
file, and ensure the documented ignore/commit workflow keeps that file out of
version control without claiming the committed configuration is always safe
after containing secrets.
- Around line 164-170: Update the private-CA connection example in the RESTish
documentation to include the --rsh-ca-cert option alongside --spec, showing how
to provide the custom CA certificate while preserving the explicit OpenAPI URL
example.
- Around line 154-162: Update the follow-up Restish command examples in the
personal-connection section to use the registered API name pgedge-sandbox
instead of pgedge. Keep shared-API examples unchanged, and ensure commands for
inspecting or deleting the personal API target pgedge-sandbox consistently.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 924a4e99-8725-4105-9cce-5b5ecd489211
📒 Files selected for processing (2)
docs/api/restish.mdmkdocs.yml
Addresses review findings against the guide added in 92dabb6: - Stop putting a real password in the committed databases/example.json example. The initial create-database call now sources secrets from a separate, deleted-after-use file, and the "Handling Secrets" section describes that actual workflow instead of claiming a file that once held a credential is safe after the fact. - Add --rsh-ca-cert to the private-CA connection example; --spec alone only fixes discovery failures; it doesn't establish trust for a private CA. - Make the personal-connection follow-up commands (api inspect, --help) consistently target pgedge-sandbox instead of mixing in the shared pgedge name.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/api/restish.md`:
- Around line 219-243: The example workflow should securely manage the temporary
JSON file containing the database password: set a restrictive umask, create the
file with mktemp, register an EXIT trap to remove it, write the payload to that
generated path, and pass that path to restish. Apply the same lifecycle changes
to the additional example referenced by the comment, and limit any cleanup claim
to the committed temporary file.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 3e22b3b0-e7b3-4b14-879b-aeddf1b1d156
📒 Files selected for processing (1)
docs/api/restish.md
Comment on lines
+219
to
+243
| ```sh | ||
| cat > /tmp/example.create.json <<'EOF' | ||
| { | ||
| "id": "example", | ||
| "spec": { | ||
| "database_name": "example", | ||
| "database_users": [ | ||
| { | ||
| "username": "admin", | ||
| "password": "changeme", | ||
| "db_owner": true, | ||
| "attributes": ["SUPERUSER", "LOGIN"] | ||
| } | ||
| ], | ||
| "port": 5432, | ||
| "nodes": [ | ||
| { "name": "n1", "host_ids": ["host-1"] }, | ||
| { "name": "n2", "host_ids": ["host-2"] }, | ||
| { "name": "n3", "host_ids": ["host-3"] } | ||
| ] | ||
| } | ||
| } | ||
| EOF | ||
| restish pgedge create-database < /tmp/example.create.json | ||
| rm /tmp/example.create.json |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
Create and remove the temporary secret file securely.
cat > /tmp/example.create.json uses a predictable path and does not set restrictive permissions. An interrupted shell can also leave the password in /tmp.
Use umask 077, mktemp, and an EXIT trap. Narrow the later claim to the committed file unless the temporary-file lifecycle is secured.
Proposed secure temporary-file workflow
+umask 077
+secret_file="$(mktemp "${TMPDIR:-/tmp}/example.create.XXXXXX")"
+trap 'rm -f -- "$secret_file"' EXIT
-cat > /tmp/example.create.json <<'EOF'
+cat > "$secret_file" <<'EOF'
...
-restish pgedge create-database < /tmp/example.create.json
-rm /tmp/example.create.json
+restish pgedge create-database < "$secret_file"Also applies to: 278-289
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/api/restish.md` around lines 219 - 243, The example workflow should
securely manage the temporary JSON file containing the database password: set a
restrictive umask, create the file with mktemp, register an EXIT trap to remove
it, write the payload to that generated path, and pass that path to restish.
Apply the same lifecycle changes to the additional example referenced by the
comment, and limit any cleanup claim to the committed temporary file.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a guide for using restish as a cli tool. Document a quickstart process (rapid installation and experimentation), profile management, project configuration and mtls profile setup, database config files and secrets.
PLAT-671