feat: config simplification and `project use` and `project list` updates #102

alexluong · 2024-09-03T00:35:56Z

Moved many of the smaller requirements to #129.

This is a PR for the base branch of some new changes involving config updates. Currently, there's nothing to be reviewed here. I'll open a few PRs against this branch so we can keep things moving without merging to main.

Requirements from @alexbouchardd:

Scope:

Remove --api-key flag
Change hookdeck ci to take the project api key as param so hookdeck ci some-key (we can keep --api-key on this command just for backward compatibility, not document it and print a warning)
Change hookdeck login to accept an optional cli key as param so hookdeck login some-key
Add a warning when using --cli-key thats it’s deprecated and login with hookdeck login some-key and remove it from the documentation
Change config terminology from api_key to cli_key and workspace_ to project_ - workspace_ -> project_ in project use, config file creation fix, and update workspace_ to project_ #128
Fix the issue with hookdeck login --cli-key abcxyz if already logged in. It should replace your current credentials for the current profile

Other tasks related to project management that may or may not be included in this PR:

CLI

Support a --project_id flag - Gone with project use, config file creation fix, and update workspace_ to project_ #128
Allow non-interactive use of hookdeck project use by allowing passing a project id hookdeck project use tm_123

Dashboard (not related to this PR)

Expose the project_id in the project settings
Add CLI key management UI

leggetter · 2024-09-03T08:03:20Z

Prefer flags over optional args

This means login should take a cli-key flag and not an optional arg. ci should take an api-key (see next point). We don't presently have a CLI style guide, but there's the reasoning: https://devcenter.heroku.com/articles/cli-style-guide#flags

project use <project_id> may be different because the use terminology implies another parameter is effectively required, as does the following interactive functionality currently in place.

Consistent flag casing

project_id should be project-id as a flag. project_id is probably accurate for the config file.

`hookdeck ci` still takes an API Key

AFAICT hookdeck ci still takes an API Key, not a CI Key. It then uses the API Key to generate a CI Key. So, we should keep the api-key flag and terminology because it is accurate.

Discussion: CI Key management in the CLI?

hookdeck ci allows for the creation of a CLI key. Why not more directly support the creation (and eventual deletion) of CI CLI Keys from the CLI using an API Key.

This also removes the dependency on the UI change but may require an API endpoint that supports CLI Key deletion (which would be required by the UI change anyway).

alexluong · 2024-09-03T09:20:39Z

Thanks for writing these out, super clear and we're on the same page originally but you make things very clear here!

hookdeck ci allows for the creation of a CLI key. Why not more directly support the creation (and eventual deletion) of CI Keys from the CLI using an API Key.

This is a very interesting idea. I do want to clarify that we may want to manage not just "ci key" but general "cli key" as there's a slight difference between the 2. But I do think it may make a lot of sense that we support this functionality from the CLI.

Is this a sufficient solution for the security audit, @alexbouchardd?

leggetter · 2024-09-03T09:48:39Z

Thanks for writing these out, super clear and we're on the same page originally but you make things very clear here!

hookdeck ci allows for the creation of a CLI key. Why not more directly support the creation (and eventual deletion) of CI Keys from the CLI using an API Key.

This is a very interesting idea. I do want to clarify that we may want to manage not just "ci key" but general "cli key" as there's a slight difference between the 2. But I do think it may make a lot of sense that we support this functionality from the CLI.

Is this a sufficient solution for the security audit, @alexbouchardd?

Ah, sorry, I do mean "CLI Keys".

alexbouchardd · 2024-09-03T12:10:15Z

Given that you'd be authenticated with specific CLI keys, doesn't it seem odd that you could delete other keys with it?

There are two distinct considerations here:

hookdeck ci generated keys are not bound to any user but rather a project. From a user perspective, they are not aware that any CLI keys exist, and that leads me to think we shouldn't be generating CLI keys at all and use the actual API key as credentials

hookdeck login assigns a CLI key, which shouldn't grant you access to delete other CLI keys. That seems better suited to the UI where you can generate a CLI client (which gives a key) and delete clients (which invalidates the key)

alexluong · 2024-09-03T12:20:56Z

I think of it more like $ hookdeck login is an authentication mechanism. CLI key is just implementation details. After a user has logged in, their requests using the CLI key are operations made by the user. And as a user, they should be able to revoke other sessions (delete other CLI keys), and therefore I don't see that as a problem.

It's the same when folks use session tokens or something like that for the web, right? Once logged in, using one session token, a user can delete other session tokens.

hookdeck ci generated keys are not bound to any user but rather a project. From a user perspective, they are not aware that any CLI keys exist, and that leads me to think we shouldn't be generating CLI keys at all and use the actual API key as credentials

For this point, I remembered the reason we introduced the concept of "CI CLI key" (different from CLI key) because the API key and CLI key have different authorization logic. Some operations were doable with CLI key and not API key. So, CI CLI key is basically a CLI key but with a slightly different authentication context (project scope instead of user scope).

leggetter · 2024-09-03T13:04:51Z

CLI Key management would need to be authenticated with an API Key. This is the same way that hookdeck ci has to take an API Key in order to generate a CLI key. Or, that's my understanding of how it works. So, hookdeck ci is effectively generating a CLI Key and doing a hookdeck cli-key create (made-up command for effect) already.

Addition:

hookdeck login also generates a CLI Key. However, it knows the user so that CLI Key can be bound to a user.

hookdeck ci --api-key {key} can't have a user associated since there is no user context (the user isn't logged in via the browser)

alexluong · 2024-09-03T13:23:52Z

CLI Key management would need to be authenticated with an API Key.

I don't think this is the right model because we're mixing scope here.

API key: project scope, it only knows about 1 project and manages resources of that project
CLI key: user scope, it has access to everything the user has access to, so if a user is in multiple organizations with multiple projects, it can manage all of those

Why would API key be able to manage CLI key?

Regarding hookdeck ci:

API key: project scope
CI key: also project scope, so only manage resources from that project. It can be used to make a few extra calls that API keys can't. Those endpoints are related to CLI like creating CLI sessions, for example.

But because the auth context is the same, API key can manage the CI key.

leggetter · 2024-09-03T15:21:41Z

Ah! CI Key vs. CLI Key 🤯

Are we sure the platform differentiates between the two? Given the scope you speak of, I'd hope it does to some extent.

But maybe both hookdeck ci --api-key {key} and hookdeck login generate the same type of key (or token?), but those tokens are scoped? ci scopes the token to the project and login scopes to the user?

So, does Hookdeck actually have the concept of all three of:

CI Key
CLI Key
API Keys

?

How does it then change what we should call the property in the config file because calling it cli_key is inaccurate if we do differentiate between the types of keys?

alexluong · 2024-09-03T15:50:59Z

Yes, we have 3 types of tokens. They're mapped to 3 different tables in the DB. I worked on the PR that introduced the CI token, and I was mindful about differentiating it and making sure it has the right scope. Obviously I don't know if there has been any changes since.

I don't think we persist the API key in the CLI. But yes, currently in the CLI we always call the keys "API key" and store them as such in the config. Definitely something to improve for clarity sake, which is part of the scope laid out above.

but not both

leggetter · 2024-11-28T19:27:24Z

@alexluong - do we need to re-write some of the issue description to reflect the above discussions?

Scope:

Remove --api-key flag

I think we're good with the above.

Change hookdeck ci to take the project api key as param so hookdeck ci some-key (we can keep --api-key on this command just for backward compatibility, not document it and print a warning)

Despite my comment about preferring flags over args, I think this is a required arg so makes sense.

Change hookdeck login to accept an optional cli key as param so hookdeck login some-key
Add a warning when using --cli-key thats it’s deprecated and login with hookdeck login some-key and remove it from the documentation

If we add this, it should be a flag.

However, I'm actually unsure how this works and where it's used. Does it set the cli_key in the config (see below) and then perform a login with it to get the CI key?

Change config terminology from api_key to cli_key and workspace_ to project_

All good.

Fix the issue with hookdeck login --cli-key abcxyz if already logged in. It should replace your current credentials for the current profile

I don't know of this problem, but makes sense.

refactor: Config parsing & precedence

…v0.12

…tructure

…ion for TTY environments

…ct filtering logic

`project use`, config file creation fix, and update workspace_ to project_

…API key

…v0.12

Add support for pinning Hookdeck project configuration to the current directory using the --local flag. This enables per-repository project configuration for better developer experience in multi-project workflows. Implementation: - Added --local flag to 'project use' command - Implemented UseProjectLocal() method to create/update local config - Added smart default: auto-updates local config when it exists - Validates --local and --config are mutually exclusive - Displays security warning when creating local config - Refactored config writing to reduce code duplication Testing: - Created comprehensive acceptance test suite - Added helper functions for temp directory management - Tests validate flag behavior, config creation, and security warnings - 2 tests passing in CI, 4 tests ready for CLI key testing Documentation: - Updated README with complete --local flag documentation - Explained configuration file precedence (--config > local > global) - Added security guidance for credential management - Included examples for all use cases Related: Previous PRs #102, #103 that removed --local flag

chore: Update version

296daf3

leggetter mentioned this pull request Sep 9, 2024

refactor: Config parsing & precedence #103

Merged

3 tasks

alexluong added 8 commits October 15, 2024 15:02

feat: Use either global or local config file

34d9c8b

but not both

chore: Remove debug log

b7dc5df

refactor: fs interface

9496ab4

test: getConfigPath

8defd13

test: improve test semantic using expected path variable

827435b

test: Parse config with different mock config scenarios

23767be

refactor: Clean config files & reduce package's public api surface

5006f6c

test: Methods related to config updates

d5e33d0

leggetter added 10 commits June 13, 2025 09:26

Merge pull request #103 from hookdeck/refactor-config

f20260a

refactor: Config parsing & precedence

Merge branch 'main' of https://github.com/hookdeck/hookdeck-cli into …

ee82412

…v0.12

fix: ensure config.toml exists and create if doesn't

8116923

refactor: update configuration from team to project terminology and s…

b80a794

…tructure

feat: support passing project name to "project use {name}"

3b2fdc7

chore: add HTTP request debug logging (can be very verbose)

70eeadb

feat: support project use [org [project]]

db686c0

chore(docs): enhance login instructions and add interactive login opt…

34f6428

…ion for TTY environments

chore(docs): improve profile management usage

3b0caff

chore(docs): add configuration file details and usage instructions

d3e84e4

leggetter added 6 commits June 14, 2025 14:22

chore(docs): add global flags

7d1d7ab

chore: improve API interaction logging

1f180f5

chore: add basic acceptance tests for Hookdeck CLI

90d0dbb

chore: update project management commands in README and improve proje…

c97b673

…ct filtering logic

chore: improve error messages for project selection in runProjectUseCmd

957ffce

Merge pull request #128 from hookdeck/feat/project-use-org-proj

f704741

`project use`, config file creation fix, and update workspace_ to project_

leggetter mentioned this pull request Jun 16, 2025

Clarify key types, when they are used, what permissions they have, and implement consistent usage #129

Open

6 tasks

leggetter added 3 commits June 16, 2025 11:58

fix: update environment variable name in acceptance test script

8cbf40e

fix: update environment variable for acceptance tests to use testing …

3eed949

…API key

fix: correct environment variable name in acceptance test workflow

656ce6b

leggetter changed the title ~~feat: v0.12~~ feat: config simplification and project use and project list updates Jun 16, 2025

Merge branch 'main' of https://github.com/hookdeck/hookdeck-cli into …

5f3f84d

…v0.12

leggetter marked this pull request as ready for review June 16, 2025 11:17

leggetter closed this Jun 16, 2025

leggetter deleted the v0.12 branch June 16, 2025 11:29

leggetter mentioned this pull request Nov 13, 2025

Project use: Can't use the '--local' flag #173

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: config simplification and `project use` and `project list` updates #102

feat: config simplification and `project use` and `project list` updates #102

Uh oh!

alexluong commented Sep 3, 2024 •

edited by leggetter

Loading

Uh oh!

leggetter commented Sep 3, 2024 •

edited

Loading

Uh oh!

alexluong commented Sep 3, 2024 •

edited

Loading

Uh oh!

leggetter commented Sep 3, 2024

Uh oh!

alexbouchardd commented Sep 3, 2024 •

edited

Loading

Uh oh!

alexluong commented Sep 3, 2024 •

edited

Loading

Uh oh!

leggetter commented Sep 3, 2024 •

edited

Loading

Uh oh!

alexluong commented Sep 3, 2024 •

edited

Loading

Uh oh!

leggetter commented Sep 3, 2024

Uh oh!

alexluong commented Sep 3, 2024

Uh oh!

leggetter commented Nov 28, 2024

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

feat: config simplification and project use and project list updates #102

feat: config simplification and project use and project list updates #102

Uh oh!

Conversation

alexluong commented Sep 3, 2024 • edited by leggetter Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

leggetter commented Sep 3, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Prefer flags over optional args

Consistent flag casing

hookdeck ci still takes an API Key

Discussion: CI Key management in the CLI?

Uh oh!

alexluong commented Sep 3, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

leggetter commented Sep 3, 2024

Uh oh!

alexbouchardd commented Sep 3, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alexluong commented Sep 3, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

leggetter commented Sep 3, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alexluong commented Sep 3, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

leggetter commented Sep 3, 2024

Uh oh!

alexluong commented Sep 3, 2024

Uh oh!

leggetter commented Nov 28, 2024

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

feat: config simplification and `project use` and `project list` updates #102

feat: config simplification and `project use` and `project list` updates #102

alexluong commented Sep 3, 2024 •

edited by leggetter

Loading

leggetter commented Sep 3, 2024 •

edited

Loading

`hookdeck ci` still takes an API Key

alexluong commented Sep 3, 2024 •

edited

Loading

alexbouchardd commented Sep 3, 2024 •

edited

Loading

alexluong commented Sep 3, 2024 •

edited

Loading

leggetter commented Sep 3, 2024 •

edited

Loading

alexluong commented Sep 3, 2024 •

edited

Loading