feat(tags): Add support for asset tagging

README.md

@@ -124,6 +124,10 @@ The `censeye` command allows you to perform a Censeye scan on a host. See the [c
 
 This is a WIP. See the [history command docs](./docs/commands/HISTORY.md) for more details.
 
+### Tags
+
+The `tags` command lets you label and organize assets. You can manage tags themselves (`list`, `get`, `create`, `update`, `delete`), assign and unassign them on hosts, certificates, and web properties, and list what a tag is assigned to. Assets can be given as arguments, read from a file or STDIN, or selected in bulk by a CenQL query — bulk changes run as asynchronous jobs you can track, wait on, and cancel with `censys tags operations`. See the [tags command docs](./docs/commands/TAGS.md) for more details.
+
 ### Other Commands
 
 - `$ censys org`: manage and view organization details. See the [org command docs](./docs/commands/ORG.md) for more details.

cmd/cencli/e2e/fixtures/fixtures.go

@@ -32,5 +32,6 @@ func Fixtures() map[string][]Fixture {
 		"history":   historyFixtures,
 		"credits":   creditsFixtures,
 		"org":       orgFixtures,
+		"tags":      tagsFixtures,
 	}
 }

cmd/cencli/e2e/fixtures/golden/golden.go

@@ -29,4 +29,30 @@ var (
 	OrgCreditsHelpStdout []byte
 	//go:embed org_help.out
 	OrgHelpStdout []byte
+	//go:embed tags_help.out
+	TagsHelpStdout []byte
+	//go:embed tags_list_help.out
+	TagsListHelpStdout []byte
+	//go:embed tags_get_help.out
+	TagsGetHelpStdout []byte
+	//go:embed tags_create_help.out
+	TagsCreateHelpStdout []byte
+	//go:embed tags_update_help.out
+	TagsUpdateHelpStdout []byte
+	//go:embed tags_delete_help.out
+	TagsDeleteHelpStdout []byte
+	//go:embed tags_assign_help.out
+	TagsAssignHelpStdout []byte
+	//go:embed tags_unassign_help.out
+	TagsUnassignHelpStdout []byte
+	//go:embed tags_assignments_help.out
+	TagsAssignmentsHelpStdout []byte
+	//go:embed tags_operations_help.out
+	TagsOperationsHelpStdout []byte
+	//go:embed tags_operations_list_help.out
+	TagsOperationsListHelpStdout []byte
+	//go:embed tags_operations_get_help.out
+	TagsOperationsGetHelpStdout []byte
+	//go:embed tags_operations_cancel_help.out
+	TagsOperationsCancelHelpStdout []byte
 )

cmd/cencli/e2e/fixtures/golden/root.out

@@ -17,6 +17,7 @@ Available Commands:
   history     Retrieve historical data for hosts, web properties, and certificates
   org         Manage and view organization details
   search      Execute a search query across Censys data
+  tags        Manage tags and tag assignments for your organization
   version     Print version information
   view        Retrieve information about hosts, certificates, and web properties
 

cmd/cencli/e2e/fixtures/golden/tags_assign_help.out

@@ -0,0 +1,46 @@
+Assign a tag, by its name or UUID, to one or more assets (host IPs, certificate SHA-256   
+fingerprints, or web property hostname:port).                                             
+
+Assets can be passed as positional arguments or read from a file (or STDIN) with          
+--input-file. Assets of different types can be mixed in a single call. Each asset is      
+assigned independently: if one fails the rest still proceed, and the per-asset outcomes   
+are reported.                                                                             
+
+Use --query instead to assign the tag to every asset matching a CenQL query. That starts  
+an asynchronous bulk job and reports the operation tracking it; the two input modes cannot
+be combined. Bulk assignment always asks for confirmation unless --yes is set.            
+
+Usage:
+  censys tags assign <tag> [asset...] [flags]
+
+Examples:
+  censys tags assign <tag> <ip-address>
+  censys tags assign <tag> <ip-address> <ip-address>
+  censys tags assign <tag> <hostname:port>
+  censys tags assign <tag> <sha256-fingerprint>
+  censys tags assign <tag> <ip-address> <hostname:port> # asset types can be mixed
+  censys tags assign <tag> --input-file <file>
+  censys tags assign <tag> --input-file - # read assets from STDIN
+  censys tags assign <tag> --query 'host.services.port: 22' # assign every matching asset
+  censys tags assign <tag> --query 'host.services.port: 22' --max-assets 1000
+  censys tags assign <tag> --query 'host.services.port: 22' --wait # poll until the job finishes
+
+Flags:
+  -h, --help                help for assign
+  -i, --input-file string   file to read the assets from (or - for STDIN). Overrides positional asset arguments.
+      --max-assets int      cap the number of assets a bulk job tags (requires --query). The effective cap is the smaller of this and your plan's tag asset limit.
+  -o, --org-id string       organization ID to target (personal access tokens only)
+      --query string        CenQL query selecting the assets to tag. Starts a bulk job instead of assigning explicit assets.
+      --timeout string      how long to wait before giving up (requires --wait) - use 0 for no limit (default "30m0s")
+  -w, --wait                poll the bulk job until it reaches a final status (requires --query)
+  -y, --yes                 skip the confirmation prompt (requires --query)
+
+Global Flags:
+      --debug                   enable debug logging
+      --no-color                disable ANSI colors and styles
+      --no-spinner              disable spinner during operations
+  -O, --output-format string    output format (json|yaml|tree|short|template) (default "short")
+  -q, --quiet                   suppress non-essential output
+  -S, --streaming               enable streaming output mode (NDJSON) for commands that support it
+      --timeout-http duration   per-request timeout for HTTP requests (e.g. 10s, 1m) - use 0 to disable
+

cmd/cencli/e2e/fixtures/golden/tags_assignments_help.out

@@ -0,0 +1,37 @@
+List the assets a tag, given by its name or UUID, is assigned to.                        
+
+Results can be filtered by asset, asset type, creator, and creation time. Use --streaming
+to emit each assignment as NDJSON as it is fetched.                                      
+
+Usage:
+  censys tags assignments <tag> [flags]
+
+Examples:
+  censys tags assignments my-tag # List a tag's assignments
+  censys tags assignments my-tag --asset-type host # Only host assignments
+  censys tags assignments my-tag --asset <ip-address> # Check whether one asset is assigned
+  censys tags assignments my-tag --created-after 2025-01-01T00:00:00Z # Only recent assignments
+  censys tags assignments my-tag --max-pages -1 # Fetch every page
+  censys tags assignments my-tag --streaming # Emit NDJSON as assignments are fetched
+
+Flags:
+      --asset strings           filter by one asset (host IP, certificate SHA-256 fingerprint, or web property hostname:port) - giving more than one is an error
+      --asset-type string       filter by asset type (host, web_property, certificate)
+      --created-after string    only assignments created after this time
+      --created-before string   only assignments created before this time
+      --created-by string       filter by the UUID of the assignment's creator
+  -h, --help                    help for assignments
+  -p, --max-pages int           maximum number of pages to fetch (-1 for all pages) (default 1)
+      --order-by string         sort order (create_time_asc, create_time_desc)
+  -o, --org-id string           organization ID to target (personal access tokens only)
+  -n, --page-size int           number of assignments to return per page (default 100)
+
+Global Flags:
+      --debug                   enable debug logging
+      --no-color                disable ANSI colors and styles
+      --no-spinner              disable spinner during operations
+  -O, --output-format string    output format (json|yaml|tree|short|template) (default "short")
+  -q, --quiet                   suppress non-essential output
+  -S, --streaming               enable streaming output mode (NDJSON) for commands that support it
+      --timeout-http duration   per-request timeout for HTTP requests (e.g. 10s, 1m) - use 0 to disable
+

cmd/cencli/e2e/fixtures/golden/tags_create_help.out

@@ -0,0 +1,28 @@
+Create a new tag with the given name.                                                
+
+Tag names must be unique within an organization. New tags are private by default; use
+--privacy shared to make a tag visible to all organization members.                  
+
+Usage:
+  censys tags create <name> [flags]
+
+Examples:
+  censys tags create my-tag # Create a private tag
+  censys tags create my-tag --privacy shared # Create a shared tag
+  censys tags create my-tag --description "Assets flagged for review" # Create a tag with a description
+
+Flags:
+      --description string   a human-readable description of the tag
+  -h, --help                 help for create
+  -o, --org-id string        organization ID to target (personal access tokens only)
+      --privacy string       tag visibility (private, shared) (default "private")
+
+Global Flags:
+      --debug                   enable debug logging
+      --no-color                disable ANSI colors and styles
+      --no-spinner              disable spinner during operations
+  -O, --output-format string    output format (json|yaml|tree|short|template) (default "short")
+  -q, --quiet                   suppress non-essential output
+  -S, --streaming               enable streaming output mode (NDJSON) for commands that support it
+      --timeout-http duration   per-request timeout for HTTP requests (e.g. 10s, 1m) - use 0 to disable
+

cmd/cencli/e2e/fixtures/golden/tags_delete_help.out

@@ -0,0 +1,26 @@
+Delete a tag by its name or UUID. This cannot be undone.                                 
+
+You are prompted to confirm before the tag is deleted. Use --yes to skip the prompt; in a
+non-interactive terminal --yes is required.                                              
+
+Usage:
+  censys tags delete <tag> [flags]
+
+Examples:
+  censys tags delete my-tag # Delete a tag by name (prompts for confirmation)
+  censys tags delete my-tag --yes # Delete without confirming
+
+Flags:
+  -h, --help            help for delete
+  -o, --org-id string   organization ID to target (personal access tokens only)
+  -y, --yes             skip the confirmation prompt
+
+Global Flags:
+      --debug                   enable debug logging
+      --no-color                disable ANSI colors and styles
+      --no-spinner              disable spinner during operations
+  -O, --output-format string    output format (json|yaml|tree|short|template) (default "short")
+  -q, --quiet                   suppress non-essential output
+  -S, --streaming               enable streaming output mode (NDJSON) for commands that support it
+      --timeout-http duration   per-request timeout for HTTP requests (e.g. 10s, 1m) - use 0 to disable
+

cmd/cencli/e2e/fixtures/golden/tags_get_help.out

@@ -0,0 +1,30 @@
+Retrieve a single tag by its name or UUID.                                                
+
+Tag names are unique within an organization, so a name and its ID can be used             
+interchangeably.                                                                          
+
+The tag payload carries no assignment count, so counting the assets it is assigned to     
+costs a second request. That count is always reported; if only the count fails, the tag is
+still printed and the count error follows it.                                             
+
+Usage:
+  censys tags get <tag> [flags]
+
+Examples:
+  censys tags get my-tag # Get a tag by name
+  censys tags get <tag-id> # Get a tag by UUID
+  censys tags get my-tag --output-format json # Output as JSON
+
+Flags:
+  -h, --help            help for get
+  -o, --org-id string   organization ID to target (personal access tokens only)
+
+Global Flags:
+      --debug                   enable debug logging
+      --no-color                disable ANSI colors and styles
+      --no-spinner              disable spinner during operations
+  -O, --output-format string    output format (json|yaml|tree|short|template) (default "short")
+  -q, --quiet                   suppress non-essential output
+  -S, --streaming               enable streaming output mode (NDJSON) for commands that support it
+      --timeout-http duration   per-request timeout for HTTP requests (e.g. 10s, 1m) - use 0 to disable
+

cmd/cencli/e2e/fixtures/golden/tags_help.out

@@ -0,0 +1,32 @@
+Manage tags and tag assignments for your organization.                                  
+
+Use --org-id on any subcommand to target a different organization; otherwise your stored
+organization ID is used.                                                                
+
+Usage:
+  censys tags [flags]
+  censys tags [command]
+
+Available Commands:
+  assign      Assign a tag to one or more assets
+  assignments List the assets a tag is assigned to
+  create      Create a new tag
+  delete      Delete a tag
+  get         Retrieve a single tag by name or ID
+  list        List all tags
+  operations  Track the asynchronous jobs created by bulk tag operations
+  unassign    Unassign a tag from one or more assets
+  update      Update an existing tag
+
+Flags:
+  -h, --help   help for tags
+
+Global Flags:
+      --debug                   enable debug logging
+      --no-color                disable ANSI colors and styles
+      --no-spinner              disable spinner during operations
+  -O, --output-format string    output format (json|yaml|tree|short|template) (default "short")
+  -q, --quiet                   suppress non-essential output
+  -S, --streaming               enable streaming output mode (NDJSON) for commands that support it
+      --timeout-http duration   per-request timeout for HTTP requests (e.g. 10s, 1m) - use 0 to disable
+

cmd/cencli/e2e/fixtures/golden/tags_list_help.out

@@ -0,0 +1,33 @@
+List all tags in your organization.                                                 
+
+Results can be filtered by privacy, name, and creator, and sorted by various fields.
+
+Usage:
+  censys tags list [flags]
+
+Examples:
+  censys tags list  # List all tags
+  censys tags list --privacy shared # List only shared tags
+  censys tags list --name my-tag # Filter by exact name
+  censys tags list --order-by name_desc # Sort by name descending
+  censys tags list --output-format json # Output as JSON
+
+Flags:
+      --created-by string   filter by the UUID of the tag's creator
+  -h, --help                help for list
+  -p, --max-pages int       maximum number of pages to fetch (-1 for all pages) (default 1)
+      --name string         filter by exact tag name
+      --order-by string     sort order (name_asc, name_desc, created_at_asc, created_at_desc, updated_at_asc, updated_at_desc)
+  -o, --org-id string       organization ID to target (personal access tokens only)
+  -n, --page-size int       number of tags to return per page (default 100)
+      --privacy string      filter by privacy (private, shared)
+
+Global Flags:
+      --debug                   enable debug logging
+      --no-color                disable ANSI colors and styles
+      --no-spinner              disable spinner during operations
+  -O, --output-format string    output format (json|yaml|tree|short|template) (default "short")
+  -q, --quiet                   suppress non-essential output
+  -S, --streaming               enable streaming output mode (NDJSON) for commands that support it
+      --timeout-http duration   per-request timeout for HTTP requests (e.g. 10s, 1m) - use 0 to disable
+

cmd/cencli/e2e/fixtures/golden/tags_operations_cancel_help.out

@@ -0,0 +1,26 @@
+Cancel a running bulk tag operation, identified by the tag it belongs to, given by name or
+UUID, and the operation's UUID.                                                           
+
+Cancelling stops the job from processing any more assets; it does not undo the assignments
+it has already made or removed. An operation that has already finished cannot be          
+cancelled.                                                                                
+
+Usage:
+  censys tags operations cancel <tag> <operation-id> [flags]
+
+Examples:
+  censys tags operations cancel my-tag <operation-id> # Stop a running bulk job
+
+Flags:
+  -h, --help            help for cancel
+  -o, --org-id string   organization ID to target (personal access tokens only)
+
+Global Flags:
+      --debug                   enable debug logging
+      --no-color                disable ANSI colors and styles
+      --no-spinner              disable spinner during operations
+  -O, --output-format string    output format (json|yaml|tree|short|template) (default "short")
+  -q, --quiet                   suppress non-essential output
+  -S, --streaming               enable streaming output mode (NDJSON) for commands that support it
+      --timeout-http duration   per-request timeout for HTTP requests (e.g. 10s, 1m) - use 0 to disable
+

cmd/cencli/e2e/fixtures/golden/tags_operations_get_help.out

@@ -0,0 +1,30 @@
+Retrieve a single bulk tag operation by the tag it belongs to, given by name or UUID, and
+the operation's UUID.                                                                    
+
+Use --wait to poll until the operation finishes. Waiting exits non-zero if the operation 
+ends up failed or cancelled; without --wait the command simply reports the current status
+and exits 0.                                                                             
+
+Usage:
+  censys tags operations get <tag> <operation-id> [flags]
+
+Examples:
+  censys tags operations get my-tag <operation-id> # Show an operation's current status
+  censys tags operations get my-tag <operation-id> --wait # Poll until the operation finishes
+  censys tags operations get my-tag <operation-id> --wait --timeout 5m # Give up waiting after 5 minutes
+
+Flags:
+  -h, --help             help for get
+  -o, --org-id string    organization ID to target (personal access tokens only)
+      --timeout string   how long to wait before giving up (requires --wait) - use 0 for no limit (default "30m0s")
+  -w, --wait             poll until the operation reaches a final status
+
+Global Flags:
+      --debug                   enable debug logging
+      --no-color                disable ANSI colors and styles
+      --no-spinner              disable spinner during operations
+  -O, --output-format string    output format (json|yaml|tree|short|template) (default "short")
+  -q, --quiet                   suppress non-essential output
+  -S, --streaming               enable streaming output mode (NDJSON) for commands that support it
+      --timeout-http duration   per-request timeout for HTTP requests (e.g. 10s, 1m) - use 0 to disable
+

cmd/cencli/e2e/fixtures/golden/tags_operations_help.out

@@ -0,0 +1,26 @@
+Track the asynchronous jobs created by bulk tag operations.                              
+
+Bulk assign and unassign submit a job rather than acting immediately; these commands list
+those jobs, inspect a single one, and cancel one that is still running.                  
+
+Usage:
+  censys tags operations [flags]
+  censys tags operations [command]
+
+Available Commands:
+  cancel      Cancel a running bulk tag operation
+  get         Retrieve a single bulk tag operation
+  list        List bulk tag operations
+
+Flags:
+  -h, --help   help for operations
+
+Global Flags:
+      --debug                   enable debug logging
+      --no-color                disable ANSI colors and styles
+      --no-spinner              disable spinner during operations
+  -O, --output-format string    output format (json|yaml|tree|short|template) (default "short")
+  -q, --quiet                   suppress non-essential output
+  -S, --streaming               enable streaming output mode (NDJSON) for commands that support it
+      --timeout-http duration   per-request timeout for HTTP requests (e.g. 10s, 1m) - use 0 to disable
+